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

Resources

• Python SDK
• Authentication and API keys
• Web Scraper API asynchronous requests
• Browser API