Bright Data CI Contract Lane

Overview

Keep pull-request verification credential-free and deterministic. Test the Bright Data adapter against fixtures by default, then place any necessary live probe in an independent protected job with a dedicated credential, approved target, and one-operation budget.

Prerequisites

• A repository test command and representative sanitized success and failure fixtures
• The CI workflow and Bright Data adapter paths
• Maintainer approval before creating an optional live lane

Instructions

Step 1: Audit the workflow boundary

Read the workflow and Grep for secrets, direct provider calls, artifact uploads, and execution from untrusted forks. Map every test to either the offline contract lane or the protected live lane.

Step 2: Add the required offline lane

Write or Edit the workflow so the required job runs npm ci and npm run test:brightdata:contract with BRIGHTDATA_MODE=fixture. Cover success, authentication denial, policy denial, 429, provider 5xx, malformed output, and redaction without network access.

Step 3: Isolate the optional live lane

Make the live job independent of fork and pull-request execution. Require a protected environment, maintainer authorization, an approved public target, a dedicated least-privilege secret, a single-operation ceiling, a timeout, and redacted logs.

Step 4: Prove negative behavior

Use Bash(npm:*) to run contract tests with missing and sentinel credentials. Confirm the offline job remains green without secrets and that failure artifacts contain neither credentials nor collected payloads.

Tool Discipline

Use Read and Grep to inspect workflows, adapters, and secret references. Use Write and Edit for the workflow, fixtures, tests, and runbook. Use Bash(npm:*) only for dependency installation and repository test commands; do not use it to make live Bright Data requests.

Output

• A required credential-free offline contract job
• An optional, independent protected live-probe job
• Negative-test and redaction receipts

Examples

A forked pull request runs synthetic proxy and snapshot fixtures only. A maintainer-triggered release workflow may perform one approved provider operation through a protected environment and records only status, latency, and redacted error class.

Error Handling

Bright Data Failure Triage

Overview

Separate provider, target, client, and policy failures using HTTP status, Proxy-Status, and current x-brd-* fields. Never treat an access or compliance denial as a cue to rotate products, regions, or identities.

Prerequisites

• A redacted response or snapshot receipt
• The zone, product, operation ID, and approved target class
• Access to the current Bright Data error catalog and network-status page

Instructions

Step 1: Collect minimal evidence

Read the receipt and Grep for status, Proxy-Status, x-brd-err-code, x-brd-error, x-brd-err-msg, snapshot state, and request time. Exclude credentials, full URLs, and bodies.

Step 2: Identify the layer

Classify authentication (407/client), policy (403/policy), throttling (429), peer/target (408/502), provider incident, or dataset lifecycle failure.

Step 3: Reproduce safely

Use Bash(curl:*) only for one authorized provider test endpoint or a read-only status check. Do not reproduce against a sensitive target or change network type to defeat a denial.

Step 4: Choose the response

Fix deterministic client/auth errors; back off transient/provider errors within budget; pause policy, target-data, account, empty, or persistent errors for owner review.

Tool Discipline

Use Read and Grep to analyze redacted evidence. Use Bash(curl:*) only for a bounded provider-controlled test. This workflow never writes raw response data, prints credentials, or authorizes product or identity switching.

Output

• Failure layer and documented provider code
• Retry, repair, pause, or escalate decision
• Redacted evidence bundle identifier and owner

Examples

For 429 with a per-IP code, reduce pressure and review distribution; do not automatically rotate to more identities. For a policy 403, stop. For a provider-wide incident, preserve the receipt and wait for recovery.

Error Handling

Resources

• Proxy error catalog
• Network status
…

Bright Data Browser API Run

Overview

Treat Browser API as a remote-browser data plane, not an unlimited browsing identity. Bind one browser zone, a public-target manifest, an interaction ceiling, and a minimal output schema before connecting.

Prerequisites

• A Browser API zone username/password stored in the runtime secret manager
• An approved public target and interaction manifest
• Playwright plus the reviewed Bright Data Python SDK or current documented client

Instructions

Step 1: Approve the task

Read the task manifest and Grep for login, account creation, purchase, message, or other prohibited interactions. Refuse any nonpublic or abusive workflow.

Step 2: Connect through the SDK

Build the connect URL with the official client and keep credentials out of logs.

from brightdata import BrightDataClient

client = BrightDataClient(
    browser_username=browser_user,
    browser_password=browser_password,
)
# Pass client.browser.get_connect_url() only to Playwright connect_over_cdp.

Step 3: Constrain the page

Allow only the manifest host set, cap navigation and wall time, block unnecessary assets where appropriate, and extract only named public fields. Do not add evasion behavior after a policy denial.

Step 4: Review and close

Use Bash(python:*) for fixture-backed browser tests. Persist the task ID, target class, field counts, provider errors, and policy decision; discard raw page content unless retention was explicitly approved.

Tool Discipline

Use Read and Grep to verify the manifest and existing browser adapter. Use Write and Edit for the bounded task, schema, and tests. Use Bash(python:*) for offline tests; connecting a live browser still requires the recorded authorization gates.

Output

• A bounded Browser API task manifest
• Schema-validated public fields and redacted run receipt
• Explicit close, retry, or policy-escalation result

Examples

Use Browser API for an approved public page that requires JavaScript to render a price table. Navigate only to allowlisted hosts, extract the three approved fields, close the browser in finally, and reject any redirect to authentication.

Error Handling

Resources

• …

Bright Data Async Snapshot Pipeline

Overview

Implement the documented trigger, progress, and download lifecycle as a state machine. Keep dataset identifiers and approved inputs separate from the API key; cap polling, validate terminal states, and stream results rather than loading arbitrary payloads into memory.

Prerequisites

• A reviewed dataset ID and approved public input manifest
• A named-user Bright Data API key in the runtime secret manager
• A retention, schema, maximum-record, and maximum-byte policy

Instructions

Step 1: Validate the manifest

Read the requested dataset/inputs and Grep for disallowed target classes or fields. Hash the approved input manifest before submission.

Step 2: Trigger once

Use Bash(curl:*) only against the fixed Bright Data API origin with the API key as a Bearer header.

curl --fail-with-body --request POST \
  'https://api.brightdata.com/datasets/v3/trigger?dataset_id=DATASET_ID' \
  --header "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @approved-inputs.json

Step 3: Poll deliberately

Persist the returned snapshot_id; poll GET /datasets/v3/progress/SNAPSHOT_ID with bounded attempts and provider-directed delay. Handle ready, failed, empty, expired, and still-building states explicitly.

Step 4: Download and verify

Stream GET /datasets/v3/snapshot/SNAPSHOT_ID in the approved format. Use parts for large results, hold format/compression parameters constant, enforce byte/record ceilings, and validate the schema before promotion.

Tool Discipline

Use Read and Grep for policy and schema checks. Use Write and Edit only for the manifest, state machine, tests, and redacted receipt. Use Bash(curl:*) for fixed-origin Bright Data API calls after authorization; never print the Bearer value or raw result data.

Output

• Input-manifest hash and snapshot identifier
• Bounded state-transition log without target data or credentials
• Schema/size validation and a promoted-or-quarantined result

Examples

Submit a small approved URL batch, record the returned snapshot ID, poll until ready, and stream JSON to quarantine. Reject a response whose schema, record count, or byte count exceeds the manifest even if the provider marks it ready.

Error Handling

Bright Data Cost and Usage Governance

Overview

Translate an approved workload into measurable provider and internal units, attribute them to an owner, and stop work before cost or scope escapes. Read current account and contract data at decision time; do not encode volatile prices in source.

Prerequisites

• A workload manifest with owner, purpose, target, fields, product, and schedule
• Current Bright Data usage or billing export and contract terms
• Finance-approved forecast, alert, and abort thresholds

Instructions

Step 1: Map cost-driving units

Read usage evidence and Grep the implementation for product choice, attempts, retries, concurrency, bytes, browser time, snapshot records, downloads, delivery, storage, and downstream processing. Label provider-reported units separately from local estimates.

Step 2: Attribute every operation

Write or Edit a usage envelope containing workload ID, owner, environment, product, target class, maximum attempts, maximum bytes or records, schedule, retention, and approved destination. Reject unattributed operations.

Step 3: Forecast scenarios

Calculate baseline, expected, and worst-authorized cases from current contract inputs. Model retries and duplicate processing explicitly, but do not assume a global provider request limit or a universal price.

Step 4: Enforce and reconcile

Add preflight budgets, in-run alerts, hard abort thresholds, and post-run reconciliation against provider evidence. Investigate variance by product, target, failure class, byte volume, and duplicate work before raising a budget.

Tool Discipline

Use Read and Grep for usage, billing, and implementation inspection. Use Write and Edit for the usage envelope, forecast, alerts, tests, and reconciliation record. This skill does not change a plan, purchase capacity, or run collection traffic.

Output

• Product-aware unit and ownership map
• Three-scenario forecast with sourced inputs
• Alert, abort, reconciliation, and variance controls

Examples

A batch has a maximum snapshot-record count, transfer-byte ceiling, retry budget, storage retention, and owner tag. The run stops at its authorized boundary and reconciles provider usage before the next schedule is approved.

Error Handling

Res…

Bright Data Redacted Support Bundle

Overview

Build a deterministic manifest of configuration shape, timestamps, versions, provider codes, and operation identifiers. Default-deny all raw headers and payloads, then include only explicitly allowlisted diagnostic fields.

Prerequisites

• A run receipt and named incident owner
• A private output directory with a retention deadline
• A redaction policy covering URLs, credentials, cookies, headers, and target data

Instructions

Step 1: Inventory inputs

Read the receipt and Grep candidate logs for secret names, proxy URLs, Bearer values, cookies, query strings, and target content before copying anything.

Step 2: Create the manifest

Write a small metadata file with product, zone alias, client/runtime version, UTC window, operation ID, state, and current provider error fields.

{"product":"web-scraper-api","zone_alias":"production-redacted","operation_id":"s_redacted","provider_code":"client_10000","raw_payload_included":false}

Step 3: Redact and validate

Use Edit only to remove disallowed material from the private bundle. Use Bash(python:*) to scan for configured secret values and forbidden keys; fail closed if any match remains.

Step 4: Seal the evidence

Record sorted file hashes, owner, purpose, recipient, and deletion time. Transmit only through the approved private support channel; never attach it to a public issue.

Tool Discipline

Use Read and Grep for discovery and pre-copy review. Use Write and Edit only inside the exact private bundle path. Use Bash(python:*) for local redaction and checksum checks; it must not upload the bundle or call Bright Data.

Output

• Private manifest plus allowlisted redacted diagnostics
• Zero-secret scan and sorted file-hash receipt
• Named recipient, retention deadline, and deletion owner

Examples

Include Proxy-Status, x-brd-err-code, a rounded UTC window, and an opaque snapshot ID. Exclude proxy username/password, API key, target URL query, response body, cookies, and collected records.

Error Handling

Resources

Bright Data Worker Deployment

Overview

Deploy collection as bounded workers instead of one privileged process. Separate synchronous proxy or Browser API requests from scraper triggers, snapshot polling, downloads, and destination delivery so each stage has its own authority, queue, resource ceiling, and rollback.

Prerequisites

• An approved workload manifest naming targets, fields, products, and destinations
• Managed secret references and environment-specific Bright Data resources
• Queue, object-storage, quarantine, and observability facilities

Instructions

Step 1: Inventory runtime responsibilities

Read the application and Grep for proxy requests, Browser API sessions, /datasets/v3/trigger, progress checks, snapshot downloads, and delivery calls. Assign each responsibility to the smallest worker role.

Step 2: Define admission and isolation

Write or Edit deployment manifests with separate queues and identities for request, browser, trigger, poll, download, validate, and delivery workers. Add target allowlists, byte and record ceilings, timeouts, concurrency bounds, and dead-letter routing.

Step 3: Protect data movement

Stream large snapshots to bounded storage, validate schema before downstream use, quarantine unexpected content, and require an approved destination before invoking /datasets/v3/deliver/SNAPSHOT_ID.

Step 4: Make rollout reversible

Specify health signals, queue-depth and error-class alerts, canary capacity, drain behavior, rollback version, secret revocation, and replay rules. Produce manifests and a deployment plan; do not initiate production traffic from this skill.

Tool Discipline

Use Read and Grep for topology and configuration discovery. Use Write and Edit for deployment manifests, queue contracts, policies, tests, and runbooks. This skill does not deploy, rotate credentials, create zones, or send provider requests.

Output

• Worker and queue topology with explicit trust boundaries
• Resource, data, and destination controls per stage
• Canary, drain, rollback, quarantine, and replay plan

Examples

A trigger worker creates one approved scraper job, a poller records state transitions, a downloader streams the completed snapshot to quarantine, a validator enforces the schema, and a delivery worker releases only accepted records to an approved destination.

Error Handling

Bright Data Authorized First Request

Overview

Run the smallest possible request against Bright Data's test endpoint. Keep proxy credentials out of the URL and process output, inspect current x-brd-* and Proxy-Status headers, and stop after one bounded proof.

Prerequisites

• An active non-production proxy zone and zone username/password
• Authorization to reach geo.brdtest.com from the test environment
• A log sink configured to redact authorization and proxy credentials

Instructions

Step 1: Confirm the target

Read the runbook and Grep the allowlist for geo.brdtest.com. Refuse arbitrary or authenticated targets for this proof.

Step 2: Run one request

Pass proxy authentication separately from the proxy host so the credential does not appear in the URL.

# 33335 is Bright Data's documented proxy gateway port.
curl --silent --show-error --include \
  --proxy http://brd.superproxy.io:33335 \
  --proxy-user "$BRIGHTDATA_PROXY_USERNAME:$BRIGHTDATA_PROXY_PASSWORD" \
  https://geo.brdtest.com/welcome.txt

Step 3: Classify the response

Record the HTTP status plus redacted Proxy-Status, x-brd-err-code, x-brd-error, and x-brd-err-msg values. Never retain the proxy authorization header or full username.

Step 4: Close the proof

Store the timestamp, zone alias, target, result class, and owner decision. A successful test proves connectivity only; it does not authorize production collection.

Tool Discipline

Use Read and Grep to confirm the approved target and redaction policy. Use Bash(curl:*) for exactly the bounded Bright Data test request shown here. Do not write target content, rotate identities, or retry policy denials.

Output

• One connectivity result tied to a zone alias and approved target
• Redacted provider error metadata when the request fails
• A clear pass, retry-later, or owner-escalation decision

Examples

Use a dedicated development zone and run one request to geo.brdtest.com. A 200 with expected provider metadata is a connectivity pass. A 407 is an access failure; a policy 403 is a stop condition, not a reason to switch networks.

Error Handling

Bright Data Access Bootstrap

Overview

Establish the product, identity, zone, target, and secret boundaries before any live collection. Native proxy clients use a zone username/password, while REST API clients use a named-user API key; treat them as different credentials with different blast radii.

Prerequisites

• An approved public-data purpose and target allowlist
• A Bright Data account owner who can grant only the required product and zone
• A secret manager and a non-production validation environment

Instructions

Step 1: Inventory the access path

Read the integration and Grep for existing Bright Data hosts, environment names, and secret references. Classify each call as native proxy, Browser API, or REST API before choosing credentials.

Step 2: Define the secret contract

Write an example-only configuration that declares names but contains no values.

BRIGHTDATA_API_KEY=
BRIGHTDATA_PROXY_USERNAME=
BRIGHTDATA_PROXY_PASSWORD=
BRIGHTDATA_ZONE=

Step 3: Bind ownership

Record the named owner, permitted zone, approved target classes, expiry or review condition, and revocation path. Do not reuse an account-wide API key when a zone credential is sufficient.

Step 4: Validate without disclosure

Use Bash(python:*) only to check that required names are present and mutually consistent; never print values. Run one separately approved smoke test through the product-specific workflow.

Tool Discipline

Use Read and Grep to inventory existing access. Use Write and Edit only for approved example, configuration, and runbook paths. Use Bash(python:*) for local presence/schema checks that never print secret values; this skill does not authorize a live request.

Output

• Credential-mode decision: native proxy or REST API
• Named secret bindings, owner, scope, and revocation receipt
• An approved smoke-test handoff with no credential material

Examples

For a Web Scraper API worker, bind one named-user API key in the deployment secret manager and keep proxy username/password variables absent. For a Playwright proxy client, bind only the approved zone credentials. Stop if the product or target authorization is ambiguous.

Error Handling

Bright Data Local Fixture Loop

Overview

Separate transport from parsing so ordinary development is deterministic and credential-free. The live lane is opt-in, target-allowlisted, budgeted, and incapable of silently replacing fixtures.

Prerequisites

• A repository-owned Bright Data adapter boundary
• Synthetic or approved redacted fixtures with expected schemas
• A test runner and a protected live-test environment

Instructions

Step 1: Map the boundary

Read the adapter and Grep for direct proxy/API calls in business logic. Move transport behind a narrow interface before recording fixtures.

Step 2: Create explicit modes

Write configuration with fixture as the default and live requiring three independent gates.

brightdata:
  mode: fixture
  live_requires:
    - BRIGHTDATA_LIVE_TEST=1
    - approved_target_manifest
    - bounded_cost_budget

Step 3: Test contract behavior

Add fixtures for success, 407, policy 403, 429, building, ready, failed, empty, and expired states. Test parsers against provider fields rather than copied HTML.

Step 4: Run the loop

Use Bash(npm:*) for unit and contract tests. Permit the live suite only in a protected environment, against an approved target, with a one-job ceiling and redacted receipt.

Tool Discipline

Use Read and Grep for discovery. Use Write and Edit only for the adapter, fixtures, tests, and documented configuration. Use Bash(npm:*) for the named local suites; never let a default test command send live Bright Data traffic.

Output

• A fixture-first transport adapter
• Deterministic success and failure fixtures
• A separately gated live-test receipt and explicit budget

Examples

A parser change should pass against a synthetic snapshot and recorded provider-error metadata with no credentials present. A maintainer may later enable one protected live job; its output updates no fixture automatically and is reviewed before adoption.

Error Handling

Resources

• Web Scraper API asynchronous requests
• …

Bright Data Evidence-Based Performance Tuning

Overview

Improve the slowest measured phase while preserving authorization, correctness, and cost ceilings. Choose the Bright Data product that matches the interaction, separate provider time from local queue and processing time, change one variable, and retain rollback evidence.

Prerequisites

• Approved targets and representative request or snapshot fixtures
• Baseline traces for queue, connect, provider, transfer, parse, and downstream phases
• Explicit latency, success, concurrency, byte, and cost thresholds

Instructions

Step 1: Build the baseline

Read traces and Grep for serialized work, unbounded concurrency, full-body buffering, repeated browser startup, hot polling, and retry amplification. Segment by product, target class, response size, and error class.

Step 2: Verify product fit

Use proxy requests for simple HTTP collection, Browser API when a browser session is actually required, and asynchronous scraper snapshots for batch workloads. Do not hide a product mismatch with more concurrency.

Step 3: Run one-variable experiments

Write or Edit a canary plan that changes only batch size, worker concurrency, connection reuse, browser-session reuse, polling cadence, streaming boundary, or downstream parallelism. Keep admission, byte, and cost ceilings fixed.

Step 4: Decide from evidence

Compare median and tail latency, success, 429, provider errors, bytes, queue time, and unit cost. Retain changes only when the target metric improves without violating safety, correctness, or budget constraints.

Tool Discipline

Use Read and Grep for trace and implementation analysis. Use Write and Edit for benchmarks, fixtures, canary configuration, and the decision record. This skill does not generate production load or alter live Bright Data resources.

Output

• Phase-level baseline and identified bottleneck
• One-variable experiment matrix with ceilings
• Keep or rollback decision supported by metrics

Examples

A snapshot workload spends most time parsing after download. Streamed NDJSON parsing lowers memory and tail latency in a fixed-size canary while provider concurrency and collection scope remain unchanged.

Error Handling

Resources

• …

Bright Data Production Readiness Gate

Overview

Make production promotion a fail-closed evidence decision. A green connectivity test is insufficient without target authorization, schema and data controls, secret ownership, backpressure, observability, and a tested rollback.

Prerequisites

• A release candidate tied to an approved workload manifest
• Staging results for success and documented failure classes
• Named service, data, security, finance, and rollback owners

Instructions

Step 1: Validate authority

Read approvals and Grep runtime configuration for unlisted targets, fields, products, zones, or delivery destinations. Verify public-data scope and recipient and retention decisions.

Step 2: Validate controls

Confirm secret-manager binding, environment isolation, egress allowlists, redirect denial, byte, record, and job ceilings, adaptive backpressure, redacted telemetry, and idempotent processing.

Step 3: Exercise failure paths

Write or Edit tests for revoked credentials, policy 403, 429, provider 5xx, snapshot failure or expiry, malformed schema, oversized delivery, duplicate delivery, and downstream outage.

Step 4: Canary and decide

Run a bounded approved canary through the deployment workflow. Compare authorization, success, error, latency, cost, and data-quality thresholds; promote only with a rollback receipt.

Tool Discipline

Use Read and Grep for release-evidence inspection. Use Write and Edit for missing tests, manifests, runbooks, and the decision record. This skill does not change production credentials, zones, traffic, or delivery destinations.

Output

• Pass or fail matrix for authority, safety, reliability, cost, and data
• Canary metrics and explicit promotion decision
• Rollback trigger, procedure, owner, and proof

Examples

Release one worker with a low job and byte ceiling and an approved test target. Promote only after duplicate delivery, policy denial, secret redaction, schema quarantine, and rollback drills all produce their expected receipts.

Error Handling

Resources

• Acceptable use policy
• Proxy error catalog
• …

Bright Data Adaptive Capacity Control

Overview

Bright Data does not publish one global proxy request limit. Build separate controllers for proxy traffic and dataset jobs, honor current provider signals, and keep target, cost, and policy ceilings stricter than capacity.

Prerequisites

• A workload profile with target, product, and idempotency classes
• Observed latency, error, and provider-code samples
• Owner-approved concurrency, byte, cost, and wall-time ceilings

Instructions

Step 1: Measure the lane

Read recent receipts and Grep for 429, Retry-After, provider error codes, active dataset jobs, per-IP concentration, and queue depth. Do not infer capacity from successful bursts alone.

Step 2: Separate controllers

Write independent limits for proxy requests, Browser API sessions, async triggers, progress polling, downloads, and delivery workers. One product's success must not raise another product's ceiling.

Step 3: Apply evidence-based backoff

Retry only idempotent transient work. Honor provider guidance, use bounded jitter, cap attempts and elapsed time, and open the circuit on policy, authentication, or data errors.

Step 4: Tune gradually

Edit one limit at a time, run an approved canary, compare throughput, error, and cost, and retain the lower limit unless the evidence and owner approve promotion.

Tool Discipline

Use Read and Grep to analyze redacted metrics and documented codes. Use Write and Edit for controller configuration, tests, and runbooks. This skill does not run live traffic or change Bright Data account limits.

Output

• Per-lane concurrency and queue budgets
• Retry and circuit matrix by documented failure class
• Canary comparison with rollback threshold

Examples

If dataset triggers return a tenant-specific parallel-job error, stop launching new jobs and continue bounded progress polling for owned snapshots. If proxy traffic returns a per-IP 429, reduce pressure and review distribution rather than guessing a universal rate.

Error Handling

Resources

• Proxy error catalog
• Scraper …

Bright Data Governed Collection Architecture

Overview

Design collection as a policy-governed data pipeline, not a direct application call. Separate human approval and configuration from collection workers, then quarantine and validate all results before any trusted consumer or external destination receives them.

Prerequisites

• Approved purpose, targets, fields, products, retention, recipients, and owners
• Current proxy, Browser API, scraper, snapshot, and delivery requirements
• Platform identity, queue, storage, policy, and observability capabilities

Instructions

Step 1: Discover the existing planes

Read design and runtime files and Grep for Bright Data credentials, zones, API endpoints, browser sessions, queues, snapshot storage, and downstream destinations. Mark every trust transition and uncontrolled shortcut.

Step 2: Define the topology

Write or Edit an architecture with these responsibilities:

Approval + workload registry -> admission controller -> bounded collection workers
                                                   -> quarantine storage
Quarantine -> schema/policy validation -> approved internal consumer
                                    \-> approved snapshot delivery destination
Telemetry <- redacted events, error classes, usage units, and decision receipts

Keep proxy and Browser API credentials in worker-specific secret bindings and REST API keys in authorized control-plane identities.

Step 3: Apply cross-cutting controls

Specify target and destination allowlists, least privilege, environment isolation, job and byte ceilings, backpressure, idempotency, schema validation, retention, deletion, redaction, audit evidence, and independent emergency stop.

Step 4: Challenge the design

Test policy denial, revoked credentials, 429, provider 5xx, browser timeout, snapshot failure or expiry, schema drift, duplicate delivery, storage exhaustion, and downstream outage. Require an owner and recovery decision for each path.

Tool Discipline

Use Read and Grep for topology discovery and evidence gathering. Use Write and Edit for diagrams, threat models, contracts, tests, and architecture decisions. This skill does not provision Bright Data resources or initiate collection.

Output

• Control-plane and data-plane topology with trust boundaries
• Responsibility, secret, data, and destination matrix
• Failure analysis, rollback path, and decision record

Examples

An admission controller accepts only signed workload manifests. Product-specific workers emit raw results to quarantine, validators release an approved schema, and delivery resolves only named destinations while redacted telemetry preserves an audit trail.

Error Handling

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

Resources

• Python SDK
…

Bright Data Security and Use Review

Overview

Treat legal purpose, public-data scope, account roles, zone isolation, and application controls as one authorization chain. Provider access does not replace the customer's duty to restrict targets, fields, retention, and downstream use.

Prerequisites

• An integration inventory and named business and data owner
• The Bright Data acceptable-use and account-role documentation
• Secret-manager, egress, retention, and incident-response controls

Instructions

Step 1: Approve purpose and targets

Read the use case and Grep manifests for authenticated pages, personal or sensitive fields, messaging, purchases, account creation, or other prohibited activity. Refuse nonpublic information behind login.

Step 2: Minimize identity

Choose named-user API keys or product-specific zone credentials, apply the least account role, isolate environments, and document revocation. Never encode secret values in configuration examples.

Step 3: Enforce in the application

Write target and field allowlists, maximum records and bytes, retention, rate and cost ceilings, redirect rules, and fail-closed policy handling. Provider denial cannot trigger automatic evasion.

Step 4: Test and review

Edit tests to cover disallowed hosts, login redirects, secret redaction, oversized results, policy errors, and revoked access. Record owner approval and the next review condition.

Tool Discipline

Use Read and Grep to inspect policy, roles, configuration, and tests. Use Write and Edit only for approved manifests, controls, tests, and the security receipt. This skill grants no live collection or account-administration authority.

Output

• Purpose, target, and data authorization matrix
• Least-privilege identity and revocation plan
• Application guardrails, negative tests, and review receipt

Examples

Authorize a public product-price dataset with named fields and short retention. Deny login redirects and free-form URLs, bind one production zone to one worker role, and make every policy 403 a hard stop.

Error Handling

Resources

• Acceptable use policy
• …

Bright Data Contract Migration

Overview

Inventory the exact current behavior before changing dependencies or products. Treat an SDK update, API endpoint change, Browser API rename, and product migration as separate changes with separate rollback boundaries.

Prerequisites

• A pinned current dependency or configuration and documented target contract
• Golden synthetic fixtures plus representative redacted receipts
• A dual-read or feature-flag path and rollback owner

Instructions

Step 1: Build the delta

Read the lockfile, adapter, and runbooks; Grep for x-luminati, old product names, obsolete endpoints, raw vendor response coupling, and undocumented ports.

Step 2: Update one boundary

Write the target dependency, API, or header mapping. Current diagnostics use Proxy-Status and x-brd-*; Browser API replaces the former Scraping Browser name. Do not invent version transitions.

Step 3: Verify compatibility

Edit fixture tests for success, authentication, policy, throttle, lifecycle, schema, and delivery states. Use Bash(python:*) for the pinned type and test suite and compare normalized outputs.

Step 4: Canary and retire

Run an authorized feature-flag canary, compare data and operational receipts, then remove the old path only after rollback expiry and owner signoff.

Tool Discipline

Use Read and Grep for the migration inventory. Use Write and Edit for dependency, adapter, fixture, and runbook changes. Use Bash(python:*) for local tests; it does not authorize live migration traffic or credential changes.

Output

• Current-to-target contract matrix
• Passing old and new fixture comparison and canary receipt
• Rollback path plus explicit old-contract retirement decision

Examples

First replace parsing of x-luminati-error with current x-brd-error and Proxy-Status fixtures. Keep a short dual-read window for retained historical receipts, but require current fields from new live responses.

Error Handling

Resources

• Python SDK
• Proxy error catalog
…

Bright Data Snapshot Delivery Receiver

Overview

Treat snapshot delivery as an untrusted, repeatable data-transfer event. Configure delivery with the current POST /datasets/v3/deliver/SNAPSHOT_ID API, authenticate the managed destination, stream the body, validate it, and make downstream processing idempotent.

Prerequisites

• A completed approved snapshot and its expected schema
• A managed HTTPS endpoint with destination authentication
• Durable quarantine storage and a replay ledger

Instructions

Step 1: Establish the delivery contract

Read the receiver and Grep for body buffering, unauthenticated routes, hard-coded provider IPs, guessed retry schedules, and direct writes to trusted tables. Record the expected schema, format, destination, and ownership.

Step 2: Configure an approved destination

Write or Edit the integration so an authorized control-plane client requests POST /datasets/v3/deliver/SNAPSHOT_ID with type=webhook and managed destination authentication. Never place destination credentials in the URL or logs.

Step 3: Receive defensively

Stream the request into bounded quarantine storage. Authenticate before processing, cap bytes and duration, compute a digest, validate format and schema, and derive an idempotency key from trusted delivery context plus content digest.

Step 4: Acknowledge and replay safely

Acknowledge only after durable acceptance. Make duplicates no-ops, quarantine malformed or oversized content, and replay from retained evidence through the same validator. Do not invent provider retry or source-IP guarantees.

Tool Discipline

Use Read and Grep to inspect receiver, routing, and storage code. Use Write and Edit for receiver logic, validation, idempotency, fixtures, and the replay runbook. This skill does not invoke delivery or expose a public endpoint.

Output

• Authenticated streaming receiver contract
• Schema, idempotency, quarantine, and replay implementation
• Redaction-safe success and failure tests

Examples

The receiver authenticates a managed header, streams NDJSON to quarantine while hashing it, rejects an unexpected schema, and promotes a validated object exactly once even if the same payload arrives again.

Error Handling