Bright Data Typed Client Boundary
Overview
Use the official Python SDK where it matches the workload, but keep product choice, authorization, retry policy, and domain schemas outside vendor objects. Pin the dependency and expose a small application-owned interface.
Prerequisites
- A Python project with a lockfile and supported runtime
- An approved Bright Data product and credential mode
- Synthetic contract fixtures for every exposed operation
Instructions
Step 1: Pin and inspect
Read the lockfile and Grep for direct Bright Data imports. Pin the reviewed SDK release through the repository dependency workflow rather than embedding a version in this skill.
Step 2: Define the port
Write an application interface that returns normalized records and provider receipts, not raw SDK response objects.
from dataclasses import dataclass
@dataclass(frozen=True)
class CollectionReceipt:
operation_id: str
state: str
records: int | None
provider_code: str | None
Step 3: Implement adapters
Keep API-key, proxy-zone, and Browser API adapters separate. Map documented terminal states and current x-brd-* errors into stable application failure classes.
Step 4: Verify the seam
Use Bash(python:*) to run type checks and fixture tests. Compare the locked SDK behavior with the current official SDK docs before any upgrade.
Tool Discipline
Use Read and Grep to locate dependency and transport boundaries. Use Write and Edit for the typed port, provider adapters, and tests. Use Bash(python:*) only for local type/test commands; live SDK calls require a separate authorized workflow.
Output
- Pinned SDK dependency and application-owned port
- Separate credential/product adapters
- Normalized receipts and fixture-backed failure mapping
Examples
Expose trigger_collection, get_progress, and download_snapshot through your own protocol. Keep a vendor response fixture at the boundary, map it once, and let downstream code depend only on CollectionReceipt.
Error Handling
| Failure | Meaning | Response |
|---|---|---|
| SDK object escapes the adapter | Provider coupling reaches domain code | Normalize the response at the boundary |
| Upgrade changes a field or state | Lockfile moved without contract review | Hold the upgrade and refresh fixtures from documentation |
| Client selects a product implicitly | Policy and cost behavior become hidden | Require an explicit product configuration |