airbyte-agent-amazon-ads 0.1.17__tar.gz → 0.1.25__tar.gz

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.
Files changed (63) hide show
  1. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/CHANGELOG.md +40 -0
  2. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/PKG-INFO +5 -4
  3. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/README.md +4 -3
  4. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/__init__.py +2 -0
  5. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/cloud_utils/client.py +125 -0
  6. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/connector_model_loader.py +5 -0
  7. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/hosted_executor.py +59 -25
  8. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/local_executor.py +87 -12
  9. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/models.py +12 -0
  10. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/http/adapters/httpx_adapter.py +10 -1
  11. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/base.py +11 -0
  12. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/operations.py +10 -0
  13. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/security.py +5 -0
  14. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/telemetry/tracker.py +4 -4
  15. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/types.py +20 -1
  16. airbyte_agent_amazon_ads-0.1.25/airbyte_agent_amazon_ads/_vendored/connector_sdk/utils.py +127 -0
  17. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/validation.py +171 -2
  18. airbyte_agent_amazon_ads-0.1.25/airbyte_agent_amazon_ads/_vendored/connector_sdk/validation_replication.py +970 -0
  19. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/connector.py +235 -10
  20. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/connector_model.py +2 -1
  21. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/models.py +19 -0
  22. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/pyproject.toml +1 -1
  23. airbyte_agent_amazon_ads-0.1.17/airbyte_agent_amazon_ads/_vendored/connector_sdk/utils.py +0 -60
  24. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/.gitignore +0 -0
  25. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/AUTH.md +0 -0
  26. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/REFERENCE.md +0 -0
  27. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/__init__.py +0 -0
  28. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/__init__.py +0 -0
  29. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/auth_strategies.py +0 -0
  30. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/auth_template.py +0 -0
  31. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/cloud_utils/__init__.py +0 -0
  32. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/constants.py +0 -0
  33. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/exceptions.py +0 -0
  34. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/__init__.py +0 -0
  35. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/extensions.py +0 -0
  36. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/http/__init__.py +0 -0
  37. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/http/adapters/__init__.py +0 -0
  38. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/http/config.py +0 -0
  39. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/http/exceptions.py +0 -0
  40. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/http/protocols.py +0 -0
  41. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/http/response.py +0 -0
  42. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/http_client.py +0 -0
  43. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/introspection.py +0 -0
  44. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/logging/__init__.py +0 -0
  45. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/logging/logger.py +0 -0
  46. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/logging/types.py +0 -0
  47. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/observability/__init__.py +0 -0
  48. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/observability/config.py +0 -0
  49. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/observability/models.py +0 -0
  50. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/observability/redactor.py +0 -0
  51. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/observability/session.py +0 -0
  52. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/performance/__init__.py +0 -0
  53. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/performance/instrumentation.py +0 -0
  54. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/performance/metrics.py +0 -0
  55. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/__init__.py +0 -0
  56. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/components.py +0 -0
  57. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/connector.py +0 -0
  58. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/extensions.py +0 -0
  59. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/secrets.py +0 -0
  60. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/telemetry/__init__.py +0 -0
  61. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/telemetry/config.py +0 -0
  62. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/_vendored/connector_sdk/telemetry/events.py +0 -0
  63. {airbyte_agent_amazon_ads-0.1.17 → airbyte_agent_amazon_ads-0.1.25}/airbyte_agent_amazon_ads/types.py +0 -0
@@ -1,5 +1,45 @@
1
1
  # Amazon Ads changelog
2
2
 
3
+ ## [0.1.25] - 2026-02-02
4
+ - Updated connector definition (YAML version 1.0.5)
5
+ - Source commit: 9d9866b0
6
+ - SDK version: 0.1.0
7
+
8
+ ## [0.1.24] - 2026-01-30
9
+ - Updated connector definition (YAML version 1.0.5)
10
+ - Source commit: b184da3e
11
+ - SDK version: 0.1.0
12
+
13
+ ## [0.1.23] - 2026-01-30
14
+ - Updated connector definition (YAML version 1.0.5)
15
+ - Source commit: 5f65d643
16
+ - SDK version: 0.1.0
17
+
18
+ ## [0.1.22] - 2026-01-30
19
+ - Updated connector definition (YAML version 1.0.4)
20
+ - Source commit: 5b20f488
21
+ - SDK version: 0.1.0
22
+
23
+ ## [0.1.21] - 2026-01-30
24
+ - Updated connector definition (YAML version 1.0.4)
25
+ - Source commit: a3729d85
26
+ - SDK version: 0.1.0
27
+
28
+ ## [0.1.20] - 2026-01-29
29
+ - Updated connector definition (YAML version 1.0.4)
30
+ - Source commit: 43200eed
31
+ - SDK version: 0.1.0
32
+
33
+ ## [0.1.19] - 2026-01-29
34
+ - Updated connector definition (YAML version 1.0.4)
35
+ - Source commit: c718c683
36
+ - SDK version: 0.1.0
37
+
38
+ ## [0.1.18] - 2026-01-28
39
+ - Updated connector definition (YAML version 1.0.4)
40
+ - Source commit: 97007bbd
41
+ - SDK version: 0.1.0
42
+
3
43
  ## [0.1.17] - 2026-01-28
4
44
  - Updated connector definition (YAML version 1.0.4)
5
45
  - Source commit: f6c6fca2
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: airbyte-agent-amazon-ads
3
- Version: 0.1.17
3
+ Version: 0.1.25
4
4
  Summary: Airbyte Amazon-Ads Connector for AI platforms
5
5
  Project-URL: Homepage, https://github.com/airbytehq/airbyte-agent-connectors
6
6
  Project-URL: Documentation, https://docs.airbyte.com/ai-agents/
@@ -135,6 +135,7 @@ See the official [Amazon-Ads API reference](https://advertising.amazon.com/API/d
135
135
 
136
136
  ## Version information
137
137
 
138
- - **Package version:** 0.1.17
139
- - **Connector version:** 1.0.4
140
- - **Generated with Connector SDK commit SHA:** f6c6fca292b291b200b31e4056856465129ae703
138
+ - **Package version:** 0.1.25
139
+ - **Connector version:** 1.0.5
140
+ - **Generated with Connector SDK commit SHA:** 9d9866b0aae8c3494d04d34e193b9bd860bfc1c6
141
+ - **Changelog:** [View changelog](https://github.com/airbytehq/airbyte-agent-connectors/blob/main/connectors/amazon-ads/CHANGELOG.md)
@@ -102,6 +102,7 @@ See the official [Amazon-Ads API reference](https://advertising.amazon.com/API/d
102
102
 
103
103
  ## Version information
104
104
 
105
- - **Package version:** 0.1.17
106
- - **Connector version:** 1.0.4
107
- - **Generated with Connector SDK commit SHA:** f6c6fca292b291b200b31e4056856465129ae703
105
+ - **Package version:** 0.1.25
106
+ - **Connector version:** 1.0.5
107
+ - **Generated with Connector SDK commit SHA:** 9d9866b0aae8c3494d04d34e193b9bd860bfc1c6
108
+ - **Changelog:** [View changelog](https://github.com/airbytehq/airbyte-agent-connectors/blob/main/connectors/amazon-ads/CHANGELOG.md)
@@ -15,6 +15,7 @@ from .models import (
15
15
  DynamicBiddingPlacementbiddingItem,
16
16
  DynamicBidding,
17
17
  CampaignBudget,
18
+ AmazonAdsCheckResult,
18
19
  AmazonAdsExecuteResult,
19
20
  AmazonAdsExecuteResultWithMeta,
20
21
  ProfilesListResult,
@@ -51,6 +52,7 @@ __all__ = [
51
52
  "DynamicBiddingPlacementbiddingItem",
52
53
  "DynamicBidding",
53
54
  "CampaignBudget",
55
+ "AmazonAdsCheckResult",
54
56
  "AmazonAdsExecuteResult",
55
57
  "AmazonAdsExecuteResultWithMeta",
56
58
  "ProfilesListResult",
@@ -161,6 +161,131 @@ class AirbyteCloudClient:
161
161
  connector_id = connectors[0]["id"]
162
162
  return connector_id
163
163
 
164
+ async def initiate_oauth(
165
+ self,
166
+ definition_id: str,
167
+ external_user_id: str,
168
+ redirect_url: str,
169
+ ) -> str:
170
+ """Initiate a server-side OAuth flow.
171
+
172
+ Starts the OAuth flow for a connector. Returns a consent URL where the
173
+ end user should be redirected to grant access. After completing consent,
174
+ they'll be redirected to your redirect_url with a `server_side_oauth_secret_id`
175
+ query parameter that can be used with `create_source()`.
176
+
177
+ Args:
178
+ definition_id: Connector definition UUID
179
+ external_user_id: Workspace identifier
180
+ redirect_url: URL where users will be redirected after OAuth consent
181
+
182
+ Returns:
183
+ The OAuth consent URL
184
+
185
+ Raises:
186
+ httpx.HTTPStatusError: If the request fails
187
+
188
+ Example:
189
+ consent_url = await client.initiate_oauth(
190
+ definition_id="d8313939-3782-41b0-be29-b3ca20d8dd3a",
191
+ external_user_id="my-workspace",
192
+ redirect_url="https://myapp.com/oauth/callback",
193
+ )
194
+ # Redirect user to: consent_url
195
+ # After consent: https://myapp.com/oauth/callback?server_side_oauth_secret_id=...
196
+ """
197
+ token = await self.get_bearer_token()
198
+ url = f"{self.API_BASE_URL}/api/v1/integrations/connectors/oauth/initiate"
199
+ headers = {"Authorization": f"Bearer {token}"}
200
+ request_body = {
201
+ "external_user_id": external_user_id,
202
+ "definition_id": definition_id,
203
+ "redirect_url": redirect_url,
204
+ }
205
+
206
+ response = await self._http_client.post(url, json=request_body, headers=headers)
207
+ response.raise_for_status()
208
+ return response.json()["consent_url"]
209
+
210
+ async def create_source(
211
+ self,
212
+ name: str,
213
+ connector_definition_id: str,
214
+ external_user_id: str,
215
+ credentials: dict[str, Any] | None = None,
216
+ replication_config: dict[str, Any] | None = None,
217
+ server_side_oauth_secret_id: str | None = None,
218
+ source_template_id: str | None = None,
219
+ ) -> str:
220
+ """Create a new source on Airbyte Cloud.
221
+
222
+ Supports two authentication modes:
223
+ 1. Direct credentials: Provide `credentials` dict
224
+ 2. Server-side OAuth: Provide `server_side_oauth_secret_id` from OAuth flow
225
+
226
+ Args:
227
+ name: Source name
228
+ connector_definition_id: UUID of the connector definition
229
+ external_user_id: User identifier
230
+ credentials: Connector auth config dict. Required unless using OAuth.
231
+ replication_config: Optional replication settings (e.g., start_date for
232
+ connectors with x-airbyte-replication-config). Required for REPLICATION
233
+ mode sources like Intercom.
234
+ server_side_oauth_secret_id: OAuth secret ID from initiate_oauth redirect.
235
+ When provided, credentials are not required.
236
+ source_template_id: Source template ID. Required when organization has
237
+ multiple source templates for this connector type.
238
+
239
+ Returns:
240
+ The created source ID (UUID string)
241
+
242
+ Raises:
243
+ httpx.HTTPStatusError: If creation fails
244
+
245
+ Example:
246
+ # With direct credentials:
247
+ source_id = await client.create_source(
248
+ name="My Intercom Source",
249
+ connector_definition_id="d8313939-3782-41b0-be29-b3ca20d8dd3a",
250
+ external_user_id="my-workspace",
251
+ credentials={"access_token": "..."},
252
+ replication_config={"start_date": "2024-01-01T00:00:00Z"}
253
+ )
254
+
255
+ # With server-side OAuth:
256
+ source_id = await client.create_source(
257
+ name="My Intercom Source",
258
+ connector_definition_id="d8313939-3782-41b0-be29-b3ca20d8dd3a",
259
+ external_user_id="my-workspace",
260
+ server_side_oauth_secret_id="airbyte_oauth_..._secret_...",
261
+ replication_config={"start_date": "2024-01-01T00:00:00Z"}
262
+ )
263
+ """
264
+ token = await self.get_bearer_token()
265
+ url = f"{self.API_BASE_URL}/v1/integrations/connectors"
266
+ headers = {"Authorization": f"Bearer {token}"}
267
+
268
+ request_body: dict[str, Any] = {
269
+ "name": name,
270
+ "definition_id": connector_definition_id,
271
+ "external_user_id": external_user_id,
272
+ }
273
+
274
+ if credentials is not None:
275
+ request_body["credentials"] = credentials
276
+ if replication_config is not None:
277
+ request_body["replication_config"] = replication_config
278
+ if server_side_oauth_secret_id is not None:
279
+ request_body["server_side_oauth_secret_id"] = server_side_oauth_secret_id
280
+ if source_template_id is not None:
281
+ request_body["source_template_id"] = source_template_id
282
+
283
+ response = await self._http_client.post(url, json=request_body, headers=headers)
284
+ response.raise_for_status()
285
+
286
+ data = response.json()
287
+ return data["id"]
288
+
164
289
  async def execute_connector(
165
290
  self,
166
291
  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 takes an external_user_id and uses the AirbyteCloudClient to:
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 user ID, credentials, and connector definition ID
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
- connector_definition_id: str,
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
- connector_definition_id: Connector definition ID used to look up
66
- the user's connector.
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. Get connector definition id from executor config
90
- 2. Look up the user's connector ID
91
- 3. Execute the connector operation via the cloud API
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
- span.set_attribute("connector.definition_id", self._connector_definition_id)
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
- span.set_attribute("user.external_id", self._external_user_id)
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
- # Step 1: Get connector definition id
127
- connector_definition_id = self._connector_definition_id
128
-
129
- # Step 2: Get the connector ID for this user
130
- connector_id = await self._cloud_client.get_connector_id(
131
- external_user_id=self._external_user_id,
132
- connector_definition_id=connector_definition_id,
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
- Matches user credentials against each auth option's required fields
352
- to determine which scheme to use.
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
- # Find all options where all required fields are present
371
- matching_options: list[AuthOption] = []
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
- error_message = error_data.get("message") or error_data.get("error") or str(error_data)
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
 
@@ -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.utcnow(),
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.utcnow(),
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.utcnow(),
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,