airbyte-agent-shopify 0.1.16__py3-none-any.whl → 0.1.24__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- airbyte_agent_shopify/__init__.py +2 -0
- airbyte_agent_shopify/_vendored/connector_sdk/cloud_utils/client.py +62 -0
- airbyte_agent_shopify/_vendored/connector_sdk/connector_model_loader.py +5 -0
- airbyte_agent_shopify/_vendored/connector_sdk/executor/hosted_executor.py +59 -25
- airbyte_agent_shopify/_vendored/connector_sdk/executor/local_executor.py +87 -12
- airbyte_agent_shopify/_vendored/connector_sdk/executor/models.py +12 -0
- airbyte_agent_shopify/_vendored/connector_sdk/http/adapters/httpx_adapter.py +10 -1
- airbyte_agent_shopify/_vendored/connector_sdk/introspection.py +12 -5
- airbyte_agent_shopify/_vendored/connector_sdk/schema/base.py +11 -0
- airbyte_agent_shopify/_vendored/connector_sdk/schema/operations.py +10 -0
- airbyte_agent_shopify/_vendored/connector_sdk/schema/security.py +5 -0
- airbyte_agent_shopify/_vendored/connector_sdk/telemetry/tracker.py +4 -4
- airbyte_agent_shopify/_vendored/connector_sdk/types.py +20 -1
- airbyte_agent_shopify/_vendored/connector_sdk/utils.py +67 -0
- airbyte_agent_shopify/_vendored/connector_sdk/validation.py +171 -2
- airbyte_agent_shopify/_vendored/connector_sdk/validation_replication.py +970 -0
- airbyte_agent_shopify/connector.py +154 -11
- airbyte_agent_shopify/connector_model.py +2 -1
- airbyte_agent_shopify/models.py +19 -0
- {airbyte_agent_shopify-0.1.16.dist-info → airbyte_agent_shopify-0.1.24.dist-info}/METADATA +13 -9
- {airbyte_agent_shopify-0.1.16.dist-info → airbyte_agent_shopify-0.1.24.dist-info}/RECORD +22 -21
- {airbyte_agent_shopify-0.1.16.dist-info → airbyte_agent_shopify-0.1.24.dist-info}/WHEEL +0 -0
|
@@ -88,6 +88,7 @@ from .models import (
|
|
|
88
88
|
MetafieldProductImagesListResultMeta,
|
|
89
89
|
CustomerAddressListResultMeta,
|
|
90
90
|
FulfillmentOrdersListResultMeta,
|
|
91
|
+
ShopifyCheckResult,
|
|
91
92
|
ShopifyExecuteResult,
|
|
92
93
|
ShopifyExecuteResultWithMeta,
|
|
93
94
|
CustomersListResult,
|
|
@@ -261,6 +262,7 @@ __all__ = [
|
|
|
261
262
|
"MetafieldProductImagesListResultMeta",
|
|
262
263
|
"CustomerAddressListResultMeta",
|
|
263
264
|
"FulfillmentOrdersListResultMeta",
|
|
265
|
+
"ShopifyCheckResult",
|
|
264
266
|
"ShopifyExecuteResult",
|
|
265
267
|
"ShopifyExecuteResultWithMeta",
|
|
266
268
|
"CustomersListResult",
|
|
@@ -161,6 +161,68 @@ class AirbyteCloudClient:
|
|
|
161
161
|
connector_id = connectors[0]["id"]
|
|
162
162
|
return connector_id
|
|
163
163
|
|
|
164
|
+
async def create_source(
|
|
165
|
+
self,
|
|
166
|
+
name: str,
|
|
167
|
+
connector_definition_id: str,
|
|
168
|
+
external_user_id: str,
|
|
169
|
+
credentials: dict[str, Any],
|
|
170
|
+
replication_config: dict[str, Any] | None = None,
|
|
171
|
+
) -> str:
|
|
172
|
+
"""Create a new source on Airbyte Agent Platform.
|
|
173
|
+
|
|
174
|
+
Args:
|
|
175
|
+
name: Source name
|
|
176
|
+
connector_definition_id: UUID of the connector definition
|
|
177
|
+
external_user_id: User identifier
|
|
178
|
+
credentials: Connector auth config dict
|
|
179
|
+
replication_config: Optional replication settings (e.g., start_date for
|
|
180
|
+
connectors with x-airbyte-replication-config). Required for REPLICATION
|
|
181
|
+
mode sources like Intercom.
|
|
182
|
+
|
|
183
|
+
Returns:
|
|
184
|
+
The created source ID (UUID string)
|
|
185
|
+
|
|
186
|
+
Raises:
|
|
187
|
+
httpx.HTTPStatusError: If creation fails
|
|
188
|
+
|
|
189
|
+
Example:
|
|
190
|
+
source_id = await client.create_source(
|
|
191
|
+
name="My Gong Source",
|
|
192
|
+
connector_definition_id="32382e40-3b49-4b99-9c5c-4076501914e7",
|
|
193
|
+
external_user_id="my-workspace",
|
|
194
|
+
credentials={"access_key": "...", "access_key_secret": "..."}
|
|
195
|
+
)
|
|
196
|
+
|
|
197
|
+
# For REPLICATION mode sources (e.g., Intercom):
|
|
198
|
+
source_id = await client.create_source(
|
|
199
|
+
name="My Intercom Source",
|
|
200
|
+
connector_definition_id="d8313939-3782-41b0-be29-b3ca20d8dd3a",
|
|
201
|
+
external_user_id="my-workspace",
|
|
202
|
+
credentials={"access_token": "..."},
|
|
203
|
+
replication_config={"start_date": "2024-01-01T00:00:00Z"}
|
|
204
|
+
)
|
|
205
|
+
"""
|
|
206
|
+
token = await self.get_bearer_token()
|
|
207
|
+
url = f"{self.API_BASE_URL}/v1/integrations/connectors"
|
|
208
|
+
headers = {"Authorization": f"Bearer {token}"}
|
|
209
|
+
|
|
210
|
+
request_body: dict[str, Any] = {
|
|
211
|
+
"name": name,
|
|
212
|
+
"definition_id": connector_definition_id,
|
|
213
|
+
"external_user_id": external_user_id,
|
|
214
|
+
"credentials": credentials,
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
if replication_config is not None:
|
|
218
|
+
request_body["replication_config"] = replication_config
|
|
219
|
+
|
|
220
|
+
response = await self._http_client.post(url, json=request_body, headers=headers)
|
|
221
|
+
response.raise_for_status()
|
|
222
|
+
|
|
223
|
+
data = response.json()
|
|
224
|
+
return data["id"]
|
|
225
|
+
|
|
164
226
|
async def execute_connector(
|
|
165
227
|
self,
|
|
166
228
|
connector_id: str,
|
|
@@ -496,6 +496,9 @@ def convert_openapi_to_connector_model(spec: OpenAPIConnector) -> ConnectorModel
|
|
|
496
496
|
# Extract untested flag
|
|
497
497
|
untested = getattr(operation, "x_airbyte_untested", None) or False
|
|
498
498
|
|
|
499
|
+
# Extract preferred_for_check flag
|
|
500
|
+
preferred_for_check = getattr(operation, "x_airbyte_preferred_for_check", None) or False
|
|
501
|
+
|
|
499
502
|
# Create endpoint definition
|
|
500
503
|
endpoint = EndpointDefinition(
|
|
501
504
|
method=method_name.upper(),
|
|
@@ -520,6 +523,7 @@ def convert_openapi_to_connector_model(spec: OpenAPIConnector) -> ConnectorModel
|
|
|
520
523
|
graphql_body=graphql_body,
|
|
521
524
|
file_field=file_field,
|
|
522
525
|
untested=untested,
|
|
526
|
+
preferred_for_check=preferred_for_check,
|
|
523
527
|
)
|
|
524
528
|
|
|
525
529
|
# Add to entities map
|
|
@@ -1010,6 +1014,7 @@ def _parse_security_scheme_to_option(scheme_name: str, scheme: Any) -> AuthOptio
|
|
|
1010
1014
|
type=single_auth.type,
|
|
1011
1015
|
config=single_auth.config,
|
|
1012
1016
|
user_config_spec=single_auth.user_config_spec,
|
|
1017
|
+
untested=getattr(scheme, "x_airbyte_untested", False),
|
|
1013
1018
|
)
|
|
1014
1019
|
|
|
1015
1020
|
|
|
@@ -19,19 +19,26 @@ class HostedExecutor:
|
|
|
19
19
|
instead of directly calling external services. The cloud API handles all
|
|
20
20
|
connector logic, secrets management, and execution.
|
|
21
21
|
|
|
22
|
-
The executor
|
|
22
|
+
The executor uses the AirbyteCloudClient to:
|
|
23
23
|
1. Authenticate with the Airbyte Platform (bearer token with caching)
|
|
24
|
-
2. Look up the user's connector
|
|
24
|
+
2. Look up the user's connector (if connector_id not provided)
|
|
25
25
|
3. Execute the connector operation via the cloud API
|
|
26
26
|
|
|
27
27
|
Implements ExecutorProtocol.
|
|
28
28
|
|
|
29
29
|
Example:
|
|
30
|
-
# Create executor with
|
|
30
|
+
# Create executor with explicit connector_id (no lookup needed)
|
|
31
|
+
executor = HostedExecutor(
|
|
32
|
+
airbyte_client_id="client_abc123",
|
|
33
|
+
airbyte_client_secret="secret_xyz789",
|
|
34
|
+
connector_id="existing-source-uuid",
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
# Or create executor with user ID for lookup
|
|
31
38
|
executor = HostedExecutor(
|
|
32
|
-
external_user_id="user-123",
|
|
33
39
|
airbyte_client_id="client_abc123",
|
|
34
40
|
airbyte_client_secret="secret_xyz789",
|
|
41
|
+
external_user_id="user-123",
|
|
35
42
|
connector_definition_id="abc123-def456-ghi789",
|
|
36
43
|
)
|
|
37
44
|
|
|
@@ -51,28 +58,48 @@ class HostedExecutor:
|
|
|
51
58
|
|
|
52
59
|
def __init__(
|
|
53
60
|
self,
|
|
54
|
-
external_user_id: str,
|
|
55
61
|
airbyte_client_id: str,
|
|
56
62
|
airbyte_client_secret: str,
|
|
57
|
-
|
|
63
|
+
connector_id: str | None = None,
|
|
64
|
+
external_user_id: str | None = None,
|
|
65
|
+
connector_definition_id: str | None = None,
|
|
58
66
|
):
|
|
59
67
|
"""Initialize hosted executor.
|
|
60
68
|
|
|
69
|
+
Either provide connector_id directly OR (external_user_id + connector_definition_id)
|
|
70
|
+
for lookup.
|
|
71
|
+
|
|
61
72
|
Args:
|
|
62
|
-
external_user_id: User identifier in the Airbyte system
|
|
63
73
|
airbyte_client_id: Airbyte client ID for authentication
|
|
64
74
|
airbyte_client_secret: Airbyte client secret for authentication
|
|
65
|
-
|
|
66
|
-
|
|
75
|
+
connector_id: Direct connector/source ID (skips lookup if provided)
|
|
76
|
+
external_user_id: User identifier in the Airbyte system (for lookup)
|
|
77
|
+
connector_definition_id: Connector definition ID (for lookup)
|
|
78
|
+
|
|
79
|
+
Raises:
|
|
80
|
+
ValueError: If neither connector_id nor (external_user_id + connector_definition_id) provided
|
|
67
81
|
|
|
68
82
|
Example:
|
|
83
|
+
# With explicit connector_id (no lookup)
|
|
69
84
|
executor = HostedExecutor(
|
|
70
|
-
external_user_id="user-123",
|
|
71
85
|
airbyte_client_id="client_abc123",
|
|
72
86
|
airbyte_client_secret="secret_xyz789",
|
|
87
|
+
connector_id="existing-source-uuid",
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
# With lookup by user + definition
|
|
91
|
+
executor = HostedExecutor(
|
|
92
|
+
airbyte_client_id="client_abc123",
|
|
93
|
+
airbyte_client_secret="secret_xyz789",
|
|
94
|
+
external_user_id="user-123",
|
|
73
95
|
connector_definition_id="abc123-def456-ghi789",
|
|
74
96
|
)
|
|
75
97
|
"""
|
|
98
|
+
# Validate: either connector_id OR (external_user_id + connector_definition_id) required
|
|
99
|
+
if not connector_id and not (external_user_id and connector_definition_id):
|
|
100
|
+
raise ValueError("Either connector_id OR (external_user_id + connector_definition_id) must be provided")
|
|
101
|
+
|
|
102
|
+
self._connector_id = connector_id
|
|
76
103
|
self._external_user_id = external_user_id
|
|
77
104
|
self._connector_definition_id = connector_definition_id
|
|
78
105
|
|
|
@@ -86,10 +113,9 @@ class HostedExecutor:
|
|
|
86
113
|
"""Execute connector via cloud API (ExecutorProtocol implementation).
|
|
87
114
|
|
|
88
115
|
Flow:
|
|
89
|
-
1.
|
|
90
|
-
2.
|
|
91
|
-
3.
|
|
92
|
-
4. Parse the response into ExecutionResult
|
|
116
|
+
1. Use provided connector_id or look up from external_user_id + definition_id
|
|
117
|
+
2. Execute the connector operation via the cloud API
|
|
118
|
+
3. Parse the response into ExecutionResult
|
|
93
119
|
|
|
94
120
|
Args:
|
|
95
121
|
config: Execution configuration (entity, action, params)
|
|
@@ -98,7 +124,7 @@ class HostedExecutor:
|
|
|
98
124
|
ExecutionResult with success/failure status
|
|
99
125
|
|
|
100
126
|
Raises:
|
|
101
|
-
ValueError: If no connector or multiple connectors found for user
|
|
127
|
+
ValueError: If no connector or multiple connectors found for user (when doing lookup)
|
|
102
128
|
httpx.HTTPStatusError: If API returns 4xx/5xx status code
|
|
103
129
|
httpx.RequestError: If network request fails
|
|
104
130
|
|
|
@@ -114,23 +140,26 @@ class HostedExecutor:
|
|
|
114
140
|
|
|
115
141
|
with tracer.start_as_current_span("airbyte.hosted_executor.execute") as span:
|
|
116
142
|
# Add span attributes for observability
|
|
117
|
-
|
|
143
|
+
if self._connector_definition_id:
|
|
144
|
+
span.set_attribute("connector.definition_id", self._connector_definition_id)
|
|
118
145
|
span.set_attribute("connector.entity", config.entity)
|
|
119
146
|
span.set_attribute("connector.action", config.action)
|
|
120
|
-
|
|
147
|
+
if self._external_user_id:
|
|
148
|
+
span.set_attribute("user.external_id", self._external_user_id)
|
|
121
149
|
if config.params:
|
|
122
150
|
# Only add non-sensitive param keys
|
|
123
151
|
span.set_attribute("connector.param_keys", list(config.params.keys()))
|
|
124
152
|
|
|
125
153
|
try:
|
|
126
|
-
#
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
154
|
+
# Use provided connector_id or look it up
|
|
155
|
+
if self._connector_id:
|
|
156
|
+
connector_id = self._connector_id
|
|
157
|
+
else:
|
|
158
|
+
# Look up connector by external_user_id + definition_id
|
|
159
|
+
connector_id = await self._cloud_client.get_connector_id(
|
|
160
|
+
external_user_id=self._external_user_id, # type: ignore[arg-type]
|
|
161
|
+
connector_definition_id=self._connector_definition_id, # type: ignore[arg-type]
|
|
162
|
+
)
|
|
134
163
|
|
|
135
164
|
span.set_attribute("connector.connector_id", connector_id)
|
|
136
165
|
|
|
@@ -164,6 +193,11 @@ class HostedExecutor:
|
|
|
164
193
|
span.record_exception(e)
|
|
165
194
|
raise
|
|
166
195
|
|
|
196
|
+
async def check(self) -> ExecutionResult:
|
|
197
|
+
"""Perform a health check via the cloud API."""
|
|
198
|
+
config = ExecutionConfig(entity="*", action="check", params={})
|
|
199
|
+
return await self.execute(config)
|
|
200
|
+
|
|
167
201
|
def _parse_execution_result(self, response: dict) -> ExecutionResult:
|
|
168
202
|
"""Parse API response into ExecutionResult.
|
|
169
203
|
|
|
@@ -36,6 +36,7 @@ from ..types import (
|
|
|
36
36
|
EndpointDefinition,
|
|
37
37
|
EntityDefinition,
|
|
38
38
|
)
|
|
39
|
+
from ..utils import find_matching_auth_options
|
|
39
40
|
|
|
40
41
|
from .models import (
|
|
41
42
|
ActionNotSupportedError,
|
|
@@ -70,6 +71,14 @@ class _OperationContext:
|
|
|
70
71
|
self.validate_required_body_fields = executor._validate_required_body_fields
|
|
71
72
|
self.extract_records = executor._extract_records
|
|
72
73
|
|
|
74
|
+
@property
|
|
75
|
+
def standard_handler(self) -> _StandardOperationHandler | None:
|
|
76
|
+
"""Return the standard operation handler, or None if not registered."""
|
|
77
|
+
for h in self.executor._operation_handlers:
|
|
78
|
+
if isinstance(h, _StandardOperationHandler):
|
|
79
|
+
return h
|
|
80
|
+
return None
|
|
81
|
+
|
|
73
82
|
|
|
74
83
|
class _OperationHandler(Protocol):
|
|
75
84
|
"""Protocol for operation handlers."""
|
|
@@ -348,8 +357,8 @@ class LocalExecutor:
|
|
|
348
357
|
) -> tuple[AuthOption, dict[str, SecretStr]]:
|
|
349
358
|
"""Infer authentication scheme from provided credentials.
|
|
350
359
|
|
|
351
|
-
|
|
352
|
-
|
|
360
|
+
Uses shared utility find_matching_auth_options to match credentials
|
|
361
|
+
against each auth option's required fields.
|
|
353
362
|
|
|
354
363
|
Args:
|
|
355
364
|
user_credentials: User-provided credentials
|
|
@@ -367,16 +376,8 @@ class LocalExecutor:
|
|
|
367
376
|
# Get the credential keys provided by the user
|
|
368
377
|
provided_keys = set(user_credentials.keys())
|
|
369
378
|
|
|
370
|
-
#
|
|
371
|
-
matching_options
|
|
372
|
-
for option in options:
|
|
373
|
-
if option.user_config_spec and option.user_config_spec.required:
|
|
374
|
-
required_fields = set(option.user_config_spec.required)
|
|
375
|
-
if required_fields.issubset(provided_keys):
|
|
376
|
-
matching_options.append(option)
|
|
377
|
-
elif not option.user_config_spec or not option.user_config_spec.required:
|
|
378
|
-
# Option has no required fields - it matches any credentials
|
|
379
|
-
matching_options.append(option)
|
|
379
|
+
# Use shared utility to find matching options
|
|
380
|
+
matching_options = find_matching_auth_options(provided_keys, options)
|
|
380
381
|
|
|
381
382
|
# Handle matching results
|
|
382
383
|
if len(matching_options) == 0:
|
|
@@ -544,6 +545,80 @@ class LocalExecutor:
|
|
|
544
545
|
# These are "expected" execution errors - return them in ExecutionResult
|
|
545
546
|
return ExecutionResult(success=False, data={}, error=str(e))
|
|
546
547
|
|
|
548
|
+
async def check(self) -> ExecutionResult:
|
|
549
|
+
"""Perform a health check by running a lightweight list operation.
|
|
550
|
+
|
|
551
|
+
Finds the operation marked with preferred_for_check=True, or falls back
|
|
552
|
+
to the first list operation. Executes it with limit=1 to verify
|
|
553
|
+
connectivity and credentials.
|
|
554
|
+
|
|
555
|
+
Returns:
|
|
556
|
+
ExecutionResult with data containing status, error, and checked operation details.
|
|
557
|
+
"""
|
|
558
|
+
check_entity = None
|
|
559
|
+
check_endpoint = None
|
|
560
|
+
|
|
561
|
+
# Look for preferred check operation
|
|
562
|
+
for (ent_name, op_action), endpoint in self._operation_index.items():
|
|
563
|
+
if getattr(endpoint, "preferred_for_check", False):
|
|
564
|
+
check_entity = ent_name
|
|
565
|
+
check_endpoint = endpoint
|
|
566
|
+
break
|
|
567
|
+
|
|
568
|
+
# Fallback to first list operation
|
|
569
|
+
if check_endpoint is None:
|
|
570
|
+
for (ent_name, op_action), endpoint in self._operation_index.items():
|
|
571
|
+
if op_action == Action.LIST:
|
|
572
|
+
check_entity = ent_name
|
|
573
|
+
check_endpoint = endpoint
|
|
574
|
+
break
|
|
575
|
+
|
|
576
|
+
if check_endpoint is None or check_entity is None:
|
|
577
|
+
return ExecutionResult(
|
|
578
|
+
success=True,
|
|
579
|
+
data={
|
|
580
|
+
"status": "skipped",
|
|
581
|
+
"error": "No list operation available for health check",
|
|
582
|
+
},
|
|
583
|
+
)
|
|
584
|
+
|
|
585
|
+
# Find the standard handler to execute the list operation
|
|
586
|
+
standard_handler = next(
|
|
587
|
+
(h for h in self._operation_handlers if isinstance(h, _StandardOperationHandler)),
|
|
588
|
+
None,
|
|
589
|
+
)
|
|
590
|
+
|
|
591
|
+
if standard_handler is None:
|
|
592
|
+
return ExecutionResult(
|
|
593
|
+
success=True,
|
|
594
|
+
data={
|
|
595
|
+
"status": "skipped",
|
|
596
|
+
"error": "No standard handler available",
|
|
597
|
+
},
|
|
598
|
+
)
|
|
599
|
+
|
|
600
|
+
try:
|
|
601
|
+
await standard_handler.execute_operation(check_entity, Action.LIST, {"limit": 1})
|
|
602
|
+
return ExecutionResult(
|
|
603
|
+
success=True,
|
|
604
|
+
data={
|
|
605
|
+
"status": "healthy",
|
|
606
|
+
"checked_entity": check_entity,
|
|
607
|
+
"checked_action": "list",
|
|
608
|
+
},
|
|
609
|
+
)
|
|
610
|
+
except Exception as e:
|
|
611
|
+
return ExecutionResult(
|
|
612
|
+
success=False,
|
|
613
|
+
data={
|
|
614
|
+
"status": "unhealthy",
|
|
615
|
+
"error": str(e),
|
|
616
|
+
"checked_entity": check_entity,
|
|
617
|
+
"checked_action": "list",
|
|
618
|
+
},
|
|
619
|
+
error=str(e),
|
|
620
|
+
)
|
|
621
|
+
|
|
547
622
|
async def _execute_operation(
|
|
548
623
|
self,
|
|
549
624
|
entity: str,
|
|
@@ -154,6 +154,18 @@ class ExecutorProtocol(Protocol):
|
|
|
154
154
|
"""
|
|
155
155
|
...
|
|
156
156
|
|
|
157
|
+
async def check(self) -> ExecutionResult:
|
|
158
|
+
"""Perform a health check to verify connectivity and credentials.
|
|
159
|
+
|
|
160
|
+
Returns:
|
|
161
|
+
ExecutionResult with data containing:
|
|
162
|
+
- status: "healthy" or "unhealthy"
|
|
163
|
+
- error: Error message if unhealthy
|
|
164
|
+
- checked_entity: Entity used for the check
|
|
165
|
+
- checked_action: Action used for the check
|
|
166
|
+
"""
|
|
167
|
+
...
|
|
168
|
+
|
|
157
169
|
|
|
158
170
|
# ============================================================================
|
|
159
171
|
# Executor Exceptions
|
|
@@ -186,7 +186,16 @@ class HTTPXClient:
|
|
|
186
186
|
# Try to get error message from response
|
|
187
187
|
try:
|
|
188
188
|
error_data = httpx_response.json()
|
|
189
|
-
|
|
189
|
+
errors_list = error_data.get("errors")
|
|
190
|
+
if isinstance(errors_list, list):
|
|
191
|
+
|
|
192
|
+
def _extract_error(e: object) -> str:
|
|
193
|
+
if isinstance(e, dict):
|
|
194
|
+
return str(e.get("userPresentableMessage") or e.get("message") or e.get("error") or e)
|
|
195
|
+
return str(e)
|
|
196
|
+
|
|
197
|
+
errors_list = ", ".join(_extract_error(e) for e in errors_list)
|
|
198
|
+
error_message = errors_list or error_data.get("message") or error_data.get("error") or str(error_data)
|
|
190
199
|
except Exception:
|
|
191
200
|
error_message = httpx_response.text or f"HTTP {status_code} error"
|
|
192
201
|
|
|
@@ -380,7 +380,11 @@ def describe_entities(model: ConnectorModelProtocol) -> list[dict[str, Any]]:
|
|
|
380
380
|
return entities
|
|
381
381
|
|
|
382
382
|
|
|
383
|
-
def generate_tool_description(
|
|
383
|
+
def generate_tool_description(
|
|
384
|
+
model: ConnectorModelProtocol,
|
|
385
|
+
*,
|
|
386
|
+
enable_hosted_mode_features: bool = True,
|
|
387
|
+
) -> str:
|
|
384
388
|
"""Generate AI tool description from connector metadata.
|
|
385
389
|
|
|
386
390
|
Produces a detailed description that includes:
|
|
@@ -393,6 +397,7 @@ def generate_tool_description(model: ConnectorModelProtocol) -> str:
|
|
|
393
397
|
|
|
394
398
|
Args:
|
|
395
399
|
model: Object conforming to ConnectorModelProtocol (e.g., ConnectorModel)
|
|
400
|
+
enable_hosted_mode_features: When False, omit hosted-mode search guidance from the docstring.
|
|
396
401
|
|
|
397
402
|
Returns:
|
|
398
403
|
Formatted description string suitable for AI tool documentation
|
|
@@ -402,8 +407,9 @@ def generate_tool_description(model: ConnectorModelProtocol) -> str:
|
|
|
402
407
|
# at the first empty line and only keeps the initial section.
|
|
403
408
|
|
|
404
409
|
# Entity/action parameter details (including pagination params like limit, starting_after)
|
|
405
|
-
search_field_paths = _collect_search_field_paths(model)
|
|
406
|
-
|
|
410
|
+
search_field_paths = _collect_search_field_paths(model) if enable_hosted_mode_features else {}
|
|
411
|
+
# Avoid a "PARAMETERS:" header because some docstring parsers treat it as a params section marker.
|
|
412
|
+
lines.append("ENTITIES (ACTIONS + PARAMS):")
|
|
407
413
|
for entity in model.entities:
|
|
408
414
|
lines.append(f" {entity.name}:")
|
|
409
415
|
actions = getattr(entity, "actions", []) or []
|
|
@@ -427,8 +433,9 @@ def generate_tool_description(model: ConnectorModelProtocol) -> str:
|
|
|
427
433
|
lines.append(" To paginate: pass starting_after=<last_id> while has_more is true")
|
|
428
434
|
|
|
429
435
|
lines.append("GUIDELINES:")
|
|
430
|
-
|
|
431
|
-
|
|
436
|
+
if enable_hosted_mode_features:
|
|
437
|
+
lines.append(' - Prefer cached search over direct API calls when using execute(): action="search" whenever possible.')
|
|
438
|
+
lines.append(" - Direct API actions (list/get/download) are slower and should be used only if search cannot answer the query.")
|
|
432
439
|
lines.append(" - Keep results small: use params.fields, params.query.filter, small params.limit, and cursor pagination.")
|
|
433
440
|
lines.append(" - If output is too large, refine the query with tighter filters/fields/limit.")
|
|
434
441
|
|
|
@@ -126,6 +126,17 @@ class Info(BaseModel):
|
|
|
126
126
|
x_airbyte_example_questions: ExampleQuestions | None = Field(None, alias="x-airbyte-example-questions")
|
|
127
127
|
x_airbyte_cache: CacheConfig | None = Field(None, alias="x-airbyte-cache")
|
|
128
128
|
x_airbyte_replication_config: ReplicationConfig | None = Field(None, alias="x-airbyte-replication-config")
|
|
129
|
+
x_airbyte_skip_suggested_streams: list[str] = Field(
|
|
130
|
+
default_factory=list,
|
|
131
|
+
alias="x-airbyte-skip-suggested-streams",
|
|
132
|
+
description="List of Airbyte suggested streams to skip when validating cache entity coverage",
|
|
133
|
+
)
|
|
134
|
+
x_airbyte_skip_auth_methods: list[str] = Field(
|
|
135
|
+
default_factory=list,
|
|
136
|
+
alias="x-airbyte-skip-auth-methods",
|
|
137
|
+
description="List of Airbyte auth methods to skip when validating auth compatibility. "
|
|
138
|
+
"Use the SelectiveAuthenticator option key (e.g., 'Private App Credentials', 'oauth2.0')",
|
|
139
|
+
)
|
|
129
140
|
|
|
130
141
|
|
|
131
142
|
class ServerVariable(BaseModel):
|
|
@@ -86,6 +86,16 @@ class Operation(BaseModel):
|
|
|
86
86
|
"Validation will generate a warning instead of an error when cassettes are missing."
|
|
87
87
|
),
|
|
88
88
|
)
|
|
89
|
+
x_airbyte_preferred_for_check: bool | None = Field(
|
|
90
|
+
None,
|
|
91
|
+
alias="x-airbyte-preferred-for-check",
|
|
92
|
+
description=(
|
|
93
|
+
"Mark this list operation as the preferred operation for health checks. "
|
|
94
|
+
"When the CHECK action is executed, this operation will be used instead of "
|
|
95
|
+
"falling back to the first available list operation. Choose a lightweight, "
|
|
96
|
+
"always-available endpoint (e.g., users, accounts)."
|
|
97
|
+
),
|
|
98
|
+
)
|
|
89
99
|
|
|
90
100
|
# Future extensions (commented out, defined for future use)
|
|
91
101
|
# from .extensions import PaginationConfig
|
|
@@ -199,6 +199,11 @@ class SecurityScheme(BaseModel):
|
|
|
199
199
|
alias="x-airbyte-token-extract",
|
|
200
200
|
description="List of fields to extract from OAuth2 token responses and use as server variables",
|
|
201
201
|
)
|
|
202
|
+
x_airbyte_untested: bool = Field(
|
|
203
|
+
False,
|
|
204
|
+
alias="x-airbyte-untested",
|
|
205
|
+
description="Mark this auth scheme as untested to skip cassette coverage validation",
|
|
206
|
+
)
|
|
202
207
|
|
|
203
208
|
@field_validator("x_airbyte_token_extract", mode="after")
|
|
204
209
|
@classmethod
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
import logging
|
|
4
4
|
import platform
|
|
5
5
|
import sys
|
|
6
|
-
from datetime import datetime
|
|
6
|
+
from datetime import UTC, datetime
|
|
7
7
|
|
|
8
8
|
from ..observability import ObservabilitySession
|
|
9
9
|
|
|
@@ -56,7 +56,7 @@ class SegmentTracker:
|
|
|
56
56
|
|
|
57
57
|
try:
|
|
58
58
|
event = ConnectorInitEvent(
|
|
59
|
-
timestamp=datetime.
|
|
59
|
+
timestamp=datetime.now(UTC),
|
|
60
60
|
session_id=self.session.session_id,
|
|
61
61
|
user_id=self.session.user_id,
|
|
62
62
|
execution_context=self.session.execution_context,
|
|
@@ -99,7 +99,7 @@ class SegmentTracker:
|
|
|
99
99
|
|
|
100
100
|
try:
|
|
101
101
|
event = OperationEvent(
|
|
102
|
-
timestamp=datetime.
|
|
102
|
+
timestamp=datetime.now(UTC),
|
|
103
103
|
session_id=self.session.session_id,
|
|
104
104
|
user_id=self.session.user_id,
|
|
105
105
|
execution_context=self.session.execution_context,
|
|
@@ -129,7 +129,7 @@ class SegmentTracker:
|
|
|
129
129
|
|
|
130
130
|
try:
|
|
131
131
|
event = SessionEndEvent(
|
|
132
|
-
timestamp=datetime.
|
|
132
|
+
timestamp=datetime.now(UTC),
|
|
133
133
|
session_id=self.session.session_id,
|
|
134
134
|
user_id=self.session.user_id,
|
|
135
135
|
execution_context=self.session.execution_context,
|
|
@@ -15,7 +15,16 @@ from .schema.security import AirbyteAuthConfig
|
|
|
15
15
|
|
|
16
16
|
|
|
17
17
|
class Action(str, Enum):
|
|
18
|
-
"""Supported actions for Entity operations.
|
|
18
|
+
"""Supported actions for Entity operations.
|
|
19
|
+
|
|
20
|
+
Standard CRUD actions:
|
|
21
|
+
GET, CREATE, UPDATE, DELETE, LIST
|
|
22
|
+
|
|
23
|
+
Special actions:
|
|
24
|
+
API_SEARCH - Search via API endpoint
|
|
25
|
+
DOWNLOAD - Download file content
|
|
26
|
+
AUTHORIZE - OAuth authorization flow
|
|
27
|
+
"""
|
|
19
28
|
|
|
20
29
|
GET = "get"
|
|
21
30
|
CREATE = "create"
|
|
@@ -81,6 +90,10 @@ class AuthOption(BaseModel):
|
|
|
81
90
|
None,
|
|
82
91
|
description="User-facing credential specification from x-airbyte-auth-config",
|
|
83
92
|
)
|
|
93
|
+
untested: bool = Field(
|
|
94
|
+
False,
|
|
95
|
+
description="Mark this auth scheme as untested to skip cassette coverage validation",
|
|
96
|
+
)
|
|
84
97
|
|
|
85
98
|
|
|
86
99
|
class AuthConfig(BaseModel):
|
|
@@ -223,6 +236,12 @@ class EndpointDefinition(BaseModel):
|
|
|
223
236
|
description="Mark operation as untested to skip cassette validation (from x-airbyte-untested extension)",
|
|
224
237
|
)
|
|
225
238
|
|
|
239
|
+
# Health check support (Airbyte extension)
|
|
240
|
+
preferred_for_check: bool = Field(
|
|
241
|
+
False,
|
|
242
|
+
description="Mark this list operation as preferred for health checks (from x-airbyte-preferred-for-check extension)",
|
|
243
|
+
)
|
|
244
|
+
|
|
226
245
|
|
|
227
246
|
class EntityDefinition(BaseModel):
|
|
228
247
|
"""Definition of an API entity."""
|