0
# Core Connector API
1

2
Main connector functionality providing the primary interface for Airbyte framework integration. The SourceXero class serves as the entry point for all connector operations including connection validation, stream discovery, and data extraction.
3

4
## Capabilities
5

6
### Source Connector Class
7

8
The main connector class that inherits from Airbyte's YamlDeclarativeSource, providing all standard Airbyte source functionality with Xero-specific configuration.
9

10
```python { .api }
11
from typing import Tuple
12
from airbyte_cdk.sources.declarative.yaml_declarative_source import YamlDeclarativeSource
13

14
class SourceXero(YamlDeclarativeSource):
15
    """
16
    Main Airbyte source connector for Xero API.
17
    
18
    Inherits from YamlDeclarativeSource to provide declarative configuration
19
    support using manifest.yaml for stream definitions.
20
    """
21
    
22
    def __init__(self):
23
        """
24
        Initialize the Xero source connector.
25
        
26
        Automatically loads configuration from manifest.yaml file in the
27
        source_xero package directory.
28
        """
29
    
30
    def check_connection(self, logger, config: dict) -> Tuple[bool, str]:
31
        """
32
        Test connection to Xero API using provided configuration.
33
        
34
        Args:
35
            logger: Python logger instance for diagnostic output
36
            config (dict): Connection configuration containing access_token,
37
                         tenant_id, and start_date
38
        
39
        Returns:
40
            Tuple[bool, str]: (success_status, error_message)
41
                            - (True, None) for successful connection
42
                            - (False, error_details) for failed connection
43
        
44
        Raises:
45
            Various HTTP and authentication exceptions based on Xero API response
46
        """
47
    
48
    def streams(self, config: dict) -> list:
49
        """
50
        Discover and return all available data streams for the connector.
51
        
52
        Args:
53
            config (dict): Connection configuration
54
            
55
        Returns:
56
            list: List of configured stream objects (21 total streams)
57
                 Each stream object contains metadata, schema, and sync methods
58
        """
59
```
60

61
### Entry Point Function
62

63
Command-line entry point function that initializes the connector and launches it through Airbyte's framework.
64

65
```python { .api }
66
def run():
67
    """
68
    Main entry point for running the Xero source connector.
69
    
70
    Creates a SourceXero instance and launches it using Airbyte CDK's
71
    launch function with command-line arguments from sys.argv.
72
    
73
    This function is registered as the 'source-xero' console script
74
    in the package's pyproject.toml configuration.
75
    
76
    Usage:
77
        Called automatically when running 'source-xero' command or
78
        when executing the main.py module directly.
79
    """
80
```
81

82
## Usage Examples
83

84
### Basic Connector Initialization
85

86
```python
87
from source_xero import SourceXero
88
import logging
89

90
# Create logger
91
logger = logging.getLogger(__name__)
92

93
# Initialize connector
94
source = SourceXero()
95

96
# Configuration with required fields
97
config = {
98
    "access_token": "your_xero_access_token_here",
99
    "tenant_id": "your_xero_tenant_id_here", 
100
    "start_date": "2023-01-01T00:00:00Z"
101
}
102

103
# Test connection
104
is_connected, error = source.check_connection(logger, config)
105
if is_connected:
106
    print("Successfully connected to Xero API")
107
else:
108
    print(f"Connection failed: {error}")
109
```
110

111
### Stream Discovery and Information
112

113
```python
114
from source_xero import SourceXero
115

116
source = SourceXero()
117
config = {
118
    "access_token": "your_token",
119
    "tenant_id": "your_tenant", 
120
    "start_date": "2023-01-01T00:00:00Z"
121
}
122

123
# Get all available streams
124
streams = source.streams(config)
125
print(f"Total available streams: {len(streams)}")
126

127
# Stream information
128
for stream in streams:
129
    print(f"Stream Name: {stream.name}")
130
    print(f"Primary Key: {getattr(stream, 'primary_key', 'None')}")
131
    print(f"Supports Incremental: {hasattr(stream, 'incremental_sync')}")
132
    print("---")
133

134
# Expected output includes 21 streams:
135
# bank_transactions, contacts, credit_notes, invoices, manual_journals,
136
# overpayments, prepayments, purchase_orders, accounts, bank_transfers,
137
# employees, items, payments, users, branding_themes, contact_groups,
138
# currencies, organisations, repeating_invoices, tax_rates, tracking_categories
139
```
140

141
### Command Line Execution
142

143
```python
144
from source_xero.run import run
145
import sys
146

147
# Simulate command line arguments
148
sys.argv = ['source-xero', 'check', '--config', 'config.json']
149

150
# Run the connector
151
run()  # This will execute the check command
152
```
153

154
## Integration with Airbyte Framework
155

156
The SourceXero class integrates seamlessly with Airbyte's standard protocols:
157

158
- **Discovery**: Automatically exposes 21 pre-configured streams
159
- **Check Connection**: Validates authentication and API access  
160
- **Read Records**: Streams data with proper state management
161
- **Incremental Sync**: Supports cursor-based incremental updates
162
- **Schema Validation**: Enforces data types and structure per stream
163
- **Error Handling**: Provides detailed error reporting for debugging
164

165
The connector follows Airbyte's declarative pattern where stream configuration, authentication, pagination, and data transformation are defined in the manifest.yaml file rather than in Python code.