…hensive test suite (#955)

* feat(fdc): Added unit tests for Data Connect client factory and _DataConnectService

* Testing ConnectorConfig, client function, and service

* refactor(dataconnect): Addressed code review feedback and standardized docstrings/synatx

Refactored test suite to use module-level BASE_CONFIG and added parameterized client caching tests.

* feat(dataconnect): Implemented foundational Data Connect client and service architecture

Implemented ConnectorConfig dataclass, DataConnect client instance, _DataConnectService caching layer, and public client() factory function. Fixed mock recursion in test_client_successful using lambda delegation in test_data_connect.py.

* chore(dataconnect): Standardized test suite formatting to achieve 10.00/10 linter score

* refactor(dataconnect): Addressed code review feedback and optimized test suite structure

Removed duplicate client factory caching tests, moved app service loader test to unit test class, added connector property validation, and formatted parameter lists.

* chore(fdc): Updated documentation and moved integration tests
Added missing copyright headers and improved docstrings with proper formatting in dataconnect.py. Moved TestDataConnectServiceIntegration from tests/test_data_connect.py into a dedicated integration test file under integration/test_data_connect.py.

* refactor(fdc): Returned TestDataConnectServiceIntegration to tests/test_data_connect.py
Moved TestDataConnectServiceIntegration back to tests/test_data_connect.py and removed integration/test_data_connect.py.

* test(fdc): Renamed integration test class to TestDataConnectServiceWorkflow
Renamed TestDataConnectServiceIntegration to TestDataConnectServiceWorkflow in tests/test_data_connect.py to clarify that it is an in-memory unit/functional test rather than a network integration test.

…ataConnectApiClient class (#965)

*Core API Client Helpers*

- Implemented `_validate_inputs` to enforce strict validation on query structures, options, variables, and custom impersonation claims.

- Implemented `_prepare_graphql_payload` to construct the GraphQL JSON payload, seamlessly serializing variables (including nested dataclasses) and optional extensions.

- Implemented `_get_firebase_dataconnect_service_url` to dynamically build endpoint URLs for both production and local emulator hosts.

- Implemented `_get_headers` to inject standard telemetry metrics (X-Firebase-Client and x-goog-api-client).

*Validation & Serialization Refinements*

- Enforced that GraphQL variables must be either a Mapping (like standard dicts) or a dataclass.
- Added support for runtime validation of subscripted generic types (e.g., Dict, Mapping) using typing.get_origin().
- Refactored `Impersonation` to inherit from `dict`, resolving type-checking mismatches while maintaining runtime dictionary behavior. Extracted variable and impersonation validation into dedicated helper methods.

*Testing & Code Health*

- Added comprehensive unit test coverage for the client constructor, input validation, headers, and payload serialization (using realistic nested dataclasses).

…ApiClient (#969)

* feat(fdc): Add internal GraphQL request helper method and tests

Implemented _make_gql_request on _DataConnectApiClient to execute and handle responses/errors for GraphQL operations. Added corresponding unit tests in tests/test_data_connect.py.

* feat(fdc): Add GraphQL response parsing and deserialization logic

Refactored _parse_graphql_response and added robust recursive type deserialization to _DataConnectApiClient.

- Implemented _deserialize_type and _deserialize_dataclass helper methods to support nested dataclasses, generic lists (List[T]), generic dictionaries (Dict[K, V]), Unions (Union[...]), Enums, and primitive casting.
- Enhanced _make_gql_request error handling to prevent silent error swallowing when the errors key is present.
- Added comprehensive unit test coverage in tests/test_data_connect.py.

* fix(fdc): Add custom QueryError exception and GraphQL error checking helper

- Introduced QueryError subclass of FirebaseError for Data Connect GraphQL query/mutation errors and exposed it in __all__.
- Extracted _check_graphql_errors helper method on _DataConnectApiClient.
- Updated error handling for non-dictionary response payloads in _parse_graphql_response to raise InternalError.
- Note: Did not edit parse_graphql_response because we are waiting on whether this will even be a function or not.

* refactor(fdc): Remove response deserialization and use immediate client instantiation
- Removed output deserialization helpers (_extract_actual_type, _deserialize_type, _deserialize_dataclass) to return raw JSON payload dictionaries (ExecuteGraphqlResponse.data), aligning Data Connect with Firestore and Realtime Database patterns for user-defined schemas.
- Updated DataConnect.__init__ to immediately instantiate _DataConnectApiClient for consistency with Node.js and other Python Admin SDK services.
- Updated test suite in tests/test_data_connect.py to cover raw response parsing and immediate client instantiation.

* feat(fdc): Add TODO for partial errors and include response payload in error message

Added a TODO comment referencing b/406281627 for partial errors support in ExecuteGraphqlResponse and _parse_graphql_response. Updated _parse_graphql_response to include the raw response payload in the InternalError message string for improved debug visibility.

)

…soft stickiness (#972)

…Pythonic impersonation (#970)

feat(fdc): Add `execute_graphql` and `execute_graphql_read` methods and test suite

Implemented the public `execute_graphql` and `execute_graphql_read` methods on the `DataConnect` client, introducing full GraphQL query and mutation execution capabilities for the Firebase Data Connect Python SDK.

Key Changes:
- API Methods: Added `execute_graphql` and `execute_graphql_read` methods to `DataConnect` accepting GraphQL queries, `GraphqlOptions` (variables, operation names, impersonation claims), and optional response types.
- API Client (`_DataConnectApiClient`): Implemented request payload preparation, URL resolution, HTTP POST execution via `JsonHttpClient`, telemetry headers (`X-Firebase-Client`, `x-goog-api-client`, `X-Firebase-Sqlconnect-Affinity`, `X-Client-Version`), and GraphQL response parsing.
- Error Handling: Added `QueryError` exception handling for GraphQL server errors and HTTP error responses.
- Impersonation: Added `Impersonation` class supporting authenticated (`auth_claims`) and unauthenticated request impersonation with constructor validation.
- Unit Testing: Added comprehensive unit test suite in `tests/test_data_connect.py` covering option validation, payload formatting, error handling, and client instantiation.
- Integration Testing: Added end-to-end integration test suite in `integration/test_data_connect.py` running against the Data Connect emulator and production endpoints.

…Node/Admin/{version}` convention (#975)