0
# Connector Setup
1

2
Core functionality for initializing and configuring the Airbyte Notion source connector with authentication and stream management.
3

4
## Capabilities
5

6
### Main Connector Class
7

8
The primary connector class that orchestrates data extraction from Notion workspaces.
9

10
```python { .api }
11
class SourceNotion(YamlDeclarativeSource):
12
    """
13
    Main Airbyte source connector for Notion API integration.
14
    Extends YamlDeclarativeSource to combine declarative YAML configuration
15
    with custom Python streams for complex operations.
16
    """
17
    
18
    def __init__(self):
19
        """
20
        Initializes the connector with manifest.yaml configuration.
21
        Sets up declarative streams and prepares for custom stream injection.
22
        """
23
    
24
    def streams(self, config: Mapping[str, Any]) -> List[Stream]:
25
        """
26
        Returns complete list of available streams including both declarative
27
        and custom Python streams.
28
        
29
        Args:
30
            config: Connector configuration containing authentication and sync settings
31
            
32
        Returns:
33
            List of Stream objects for data extraction
34
        """
35
    
36
    def _get_authenticator(self, config: Mapping[str, Any]) -> TokenAuthenticator:
37
        """
38
        Creates and returns the appropriate authenticator based on configuration.
39
        Supports OAuth2.0, token-based, and legacy authentication methods.
40
        
41
        Args:
42
            config: Configuration mapping containing credentials
43
            
44
        Returns:
45
            TokenAuthenticator configured for the specified auth method
46
        """
47
```
48

49
### Entry Point Function
50

51
The main entry point for command-line execution of the connector.
52

53
```python { .api }
54
def run():
55
    """
56
    Main entry point for the Airbyte source connector.
57
    Initializes SourceNotion and launches with command line arguments.
58
    Used by the source-notion console script.
59
    """
60
```
61

62
## Usage Examples
63

64
### Basic Connector Initialization
65

66
```python
67
from source_notion import SourceNotion
68

69
# Initialize the connector
70
source = SourceNotion()
71

72
# OAuth2.0 configuration
73
oauth_config = {
74
    "credentials": {
75
        "auth_type": "OAuth2.0",
76
        "client_id": "your_client_id",
77
        "client_secret": "your_client_secret",
78
        "access_token": "your_oauth_token"
79
    },
80
    "start_date": "2023-01-01T00:00:00.000Z"
81
}
82

83
# Get available streams
84
streams = source.streams(oauth_config)
85
print(f"Available streams: {[stream.name for stream in streams]}")
86
```
87

88
### Token-Based Authentication
89

90
```python
91
# Token authentication configuration
92
token_config = {
93
    "credentials": {
94
        "auth_type": "token",
95
        "token": "secret_integration_token"
96
    },
97
    "start_date": "2023-01-01T00:00:00.000Z"
98
}
99

100
# Initialize and configure
101
source = SourceNotion()
102
streams = source.streams(token_config)
103

104
# Test authenticator creation
105
authenticator = source._get_authenticator(token_config)
106
```
107

108
### Legacy Configuration Support
109

110
```python
111
# Legacy format (backward compatibility)
112
legacy_config = {
113
    "access_token": "notion_token",
114
    "start_date": "2023-01-01T00:00:00.000Z"
115
}
116

117
source = SourceNotion()
118
authenticator = source._get_authenticator(legacy_config)
119
```
120

121
### Command Line Usage
122

123
```bash
124
# Using as installed console script
125
source-notion spec
126
source-notion check --config config.json
127
source-notion discover --config config.json
128
source-notion read --config config.json --catalog catalog.json
129

130
# Using Python module directly
131
python -m source_notion.run spec
132
python -m source_notion.run check --config config.json
133
```
134

135
### Integration with Airbyte CDK
136

137
```python
138
from airbyte_cdk.models import AirbyteConnectionStatus, Status
139
from airbyte_cdk.logger import AirbyteLogger
140

141
logger = AirbyteLogger()
142
source = SourceNotion()
143

144
# Test connection
145
config = {
146
    "credentials": {
147
        "auth_type": "token",
148
        "token": "your_token"
149
    }
150
}
151

152
try:
153
    status = source.check(logger, config)
154
    if status.status == Status.SUCCEEDED:
155
        print("Connection successful!")
156
    else:
157
        print(f"Connection failed: {status.message}")
158
except Exception as e:
159
    print(f"Error testing connection: {e}")
160
```
161

162
## Configuration Validation
163

164
The connector automatically handles configuration validation and provides clear error messages for common issues:
165

166
- **Missing Credentials**: Validates that either OAuth2.0 or token credentials are provided
167
- **Invalid Date Format**: Ensures start_date follows the required ISO format
168
- **Authentication Errors**: Provides specific guidance for permission and access issues
169
- **Backward Compatibility**: Automatically handles legacy configuration formats
170

171
## Stream Architecture
172

173
The connector uses a hybrid approach:
174

175
1. **Declarative Streams** (defined in manifest.yaml):
176
   - users
177
   - databases  
178
   - comments
179

180
2. **Custom Python Streams** (injected by SourceNotion.streams()):
181
   - pages (parent stream for blocks)
182
   - blocks (substream with recursive traversal)
183

184
This architecture allows leveraging Airbyte's low-code declarative framework while maintaining flexibility for complex operations like hierarchical block traversal.