0
# Client Operations
1

2
High-level client interface for managing Google Directory API interactions. The Client class provides authentication management, health checks, stream configuration, and orchestrates access to individual API endpoints.
3

4
## Capabilities
5

6
### Client Initialization
7

8
The main client class that handles Google Directory API interactions through the Airbyte CDK framework.
9

10
```python { .api }
11
class Client(BaseClient):
12
    """
13
    Main client class handling Google Directory API interactions.
14
    
15
    Extends Airbyte CDK BaseClient to provide Google Directory-specific
16
    functionality including authentication, health checks, and stream management.
17
    """
18
    
19
    def __init__(self, credentials: Mapping[str, Any] = None, credentials_json: str = None, email: str = None):
20
        """
21
        Initialize the Google Directory client.
22
        
23
        Parameters:
24
        - credentials: Dict containing authentication credentials
25
        - credentials_json: JSON string of service account credentials (legacy)
26
        - email: Admin email for service account delegation (legacy)
27
        
28
        The constructor supports both new (credentials dict) and legacy
29
        (credentials_json + email) configuration formats.
30
        """
31
```
32

33
### Health Check Operations
34

35
Verify connectivity and authentication with the Google Directory API.
36

37
```python { .api }
38
def health_check(self) -> Tuple[bool, str]:
39
    """
40
    Perform health check against Google Directory API.
41
    
42
    Tests connectivity by attempting to fetch users from the directory.
43
    
44
    Returns:
45
    - Tuple[bool, str]: (is_healthy, error_message)
46
        - is_healthy: True if connection successful, False otherwise  
47
        - error_message: None if healthy, error description if unhealthy
48
    """
49
```
50

51
### Stream Management
52

53
Access configured streams with Airbyte-specific metadata and primary key configuration.
54

55
```python { .api }
56
@property
57
def streams(self) -> Generator[AirbyteStream, None, None]:
58
    """
59
    Generator yielding AirbyteStream objects with primary keys configured.
60
    
61
    All streams are configured with source_defined_primary_key = [["id"]]
62
    to use the 'id' field as the primary key for change detection.
63
    
64
    Yields:
65
    - AirbyteStream objects for users, groups, and group_members streams
66
    """
67
```
68

69
### Stream Method Enumeration
70

71
Internal method for mapping stream names to their corresponding API list methods.
72

73
```python { .api }
74
def _enumerate_methods(self) -> Mapping[str, callable]:
75
    """
76
    Enumerate available stream methods for the Airbyte CDK.
77
    
78
    Maps stream names to their corresponding API list methods from
79
    the configured stream APIs (users, groups, group_members).
80
    
81
    Returns:
82
    - Mapping[str, callable]: Dictionary mapping stream names to list methods
83
    """
84
```
85

86
### State Management
87

88
Stream state management for incremental synchronization (not implemented in current version).
89

90
```python { .api }
91
def get_stream_state(self, name: str) -> Any:
92
    """
93
    Get stream state for incremental synchronization.
94
    
95
    Parameters:
96
    - name: Stream name
97
    
98
    Returns:
99
    - Any: Stream state (currently not implemented)
100
    """
101

102
def set_stream_state(self, name: str, state: Any):
103
    """
104
    Set stream state for incremental synchronization.
105
    
106
    Parameters:
107
    - name: Stream name
108
    - state: State to persist
109
    
110
    Currently not implemented - state management is handled by Airbyte platform.
111
    """
112
```
113

114
## Usage Examples
115

116
### Basic Client Setup with OAuth
117

118
```python
119
from source_google_directory.client import Client
120

121
# OAuth credentials configuration
122
oauth_credentials = {
123
    "client_id": "your-oauth-client-id",
124
    "client_secret": "your-oauth-client-secret",
125
    "refresh_token": "your-refresh-token"
126
}
127

128
# Initialize client
129
client = Client(credentials=oauth_credentials)
130

131
# Perform health check
132
is_healthy, error_msg = client.health_check()
133
if is_healthy:
134
    print("Connection successful!")
135
else:
136
    print(f"Connection failed: {error_msg}")
137
```
138

139
### Basic Client Setup with Service Account
140

141
```python
142
from source_google_directory.client import Client
143

144
# Service account credentials
145
service_credentials = {
146
    "credentials_json": '{"type": "service_account", "project_id": "...", ...}',
147
    "email": "admin@yourdomain.com"
148
}
149

150
# Initialize client
151
client = Client(credentials=service_credentials)
152

153
# Check connection health
154
is_healthy, error_msg = client.health_check()
155
```
156

157
### Legacy Configuration Format
158

159
```python
160
# Legacy format (still supported)
161
client = Client(
162
    credentials_json='{"type": "service_account", ...}',
163
    email="admin@yourdomain.com"
164
)
165
```
166

167
### Stream Access
168

169
```python
170
# Get available streams
171
for stream in client.streams:
172
    print(f"Stream: {stream.name}")
173
    print(f"Primary key: {stream.source_defined_primary_key}")
174
```
175

176
## Authentication Support
177

178
The client supports two Google authentication methods:
179

180
### OAuth 2.0 (Web Server Application)
181
- Requires: `client_id`, `client_secret`, `refresh_token`
182
- Use case: Interactive authentication scenarios
183
- Scopes: Directory read-only permissions
184

185
### Service Account
186
- Requires: `credentials_json`, `email` (admin email for delegation)
187
- Use case: Server-to-server authentication
188
- Setup: Requires domain-wide delegation configuration
189

190
## Internal Architecture
191

192
The Client class orchestrates several components:
193

194
- **API instance**: Core Google Directory API wrapper
195
- **Stream APIs**: Individual API handlers (UsersAPI, GroupsAPI, GroupMembersAPI)
196
- **Method enumeration**: Maps stream names to corresponding API list methods
197
- **Primary key configuration**: Sets consistent primary keys across all streams