v2.5.0: CLI-credentials auth, scraper-core dedup, X scraper

[artemo-brd]

Release PR: syncs main with dev, bringing in everything merged into dev since the last release (v2.4.1 on main).

Included PRs

#46 — v2.5.0: CLI-credentials auth + scraper-core dedup

Python half of the cross-SDK task "SDKs resolve credentials from the CLI store + report auth source in user-agent" (the JS half lives in sdk-js).

Before: the SDK only accepted a token via the token= parameter or the BRIGHTDATA_API_TOKEN env var — a user who had already run brightdata login still had to copy an API key by hand.

Now: with no token given, the SDK falls back to the key the CLI already saved. One login authenticates everything:

client=BrightDataClient() # zero configuration on a logged-in machine

Resolution order (first hit wins):

1. token= parameter → auth=param
2. BRIGHTDATA_API_TOKEN, then BRIGHTDATA_API_KEY env vars → auth=env
3. CLI store …/brightdata-cli/credentials.json (read-only) → auth=cli_credentials
4. Nothing found → actionable error (mentions brightdata login, the env var, and the token page)

Every request now reports how the token was obtained — making SDK onboarding measurable (feeds the sdk_auth_source Mixpanel property):

User-Agent: brightdata-sdk-python/2.5.0 (auth=cli_credentials)

Ticket checklist:

• src/brightdata/cli_credentials.py — per-platform path (Linux / macOS / Windows %APPDATA%) + read_cli_credentials() that never raises and never writes
• Same precedence in BrightDataClientandSyncBrightDataClient (sync delegates to async — pinned by test)
• Read-only: never writes into brightdata-cli/, never reads config.json (pinned by test)
• The token never appears in logs; only the source name is reported
• README Configuration: "Already logged in with the CLI? The SDK works with no configuration."
• Tests: every resolution path, precedence order, all 3 platform paths (mocked home / APPDATA), malformed / missing / empty credentials, and the no-credentials error — 25 new tests

Note: engines created by standalone scraper construction (e.g. AmazonScraper(bearer_token=...) without a client) keep today's behavior and omit the (auth=…) field — the ticket scopes the fallback to the client constructors; extending it there is a small follow-up.

Also included: Internal shared ScraperCore. The 7 search classes each hand-copied the base scraper's __init__ + context manager and had drifted (Amazon/ChatGPT/LinkedIn search lacked the env-token fallback). They now inherit one shared core: −174 lines, drift gone.

Tests: 321 passing (57 new). Version → 2.5.0.

Post-merge fix included in this release PR: test_raises_without_token was updated to mock read_cli_credentials(), since the new CLI fallback meant the test was not hermetic on machines with real brightdata login credentials present.

---

#43 — v2.4.1: X (Twitter) scraper + limit_per_input

Adds the X (Twitter) Web Scraper (client.scrape.x) — previously missing from the SDK.

• 5 variants: posts, posts_by_profile, posts_by_profiles_array, profiles, profiles_by_username (collect-by-URL and discover), each with async/sync + trigger/status/fetch.
• Adds limit_per_input to cap records per input (additive — other scrapers unchanged).
• Sync parity, tests, and a notebook walkthrough.
• Version → 2.4.1.

[artemo-brd]

Release PR: syncs main with dev, bringing in everything merged into dev since the last release (v2.4.1 on main).

Included PRs

#46 — v2.5.0: CLI-credentials auth + scraper-core dedup

Python half of the cross-SDK task "SDKs resolve credentials from the CLI store + report auth source in user-agent" (the JS half lives in sdk-js).

Before: the SDK only accepted a token via the token= parameter or the BRIGHTDATA_API_TOKEN env var — a user who had already run brightdata login still had to copy an API key by hand.

Now: with no token given, the SDK falls back to the key the CLI already saved. One login authenticates everything:

client=BrightDataClient() # zero configuration on a logged-in machine

Resolution order (first hit wins):

1. token= parameter → auth=param
2. BRIGHTDATA_API_TOKEN, then BRIGHTDATA_API_KEY env vars → auth=env
3. CLI store …/brightdata-cli/credentials.json (read-only) → auth=cli_credentials
4. Nothing found → actionable error (mentions brightdata login, the env var, and the token page)

Every request now reports how the token was obtained — making SDK onboarding measurable (feeds the sdk_auth_source Mixpanel property):

User-Agent: brightdata-sdk-python/2.5.0 (auth=cli_credentials)

Ticket checklist:

• src/brightdata/cli_credentials.py — per-platform path (Linux / macOS / Windows %APPDATA%) + read_cli_credentials() that never raises and never writes
• Same precedence in BrightDataClientandSyncBrightDataClient (sync delegates to async — pinned by test)
• Read-only: never writes into brightdata-cli/, never reads config.json (pinned by test)
• The token never appears in logs; only the source name is reported
• README Configuration: "Already logged in with the CLI? The SDK works with no configuration."
• Tests: every resolution path, precedence order, all 3 platform paths (mocked home / APPDATA), malformed / missing / empty credentials, and the no-credentials error — 25 new tests

Note: engines created by standalone scraper construction (e.g. AmazonScraper(bearer_token=...) without a client) keep today's behavior and omit the (auth=…) field — the ticket scopes the fallback to the client constructors; extending it there is a small follow-up.

Also included: Internal shared ScraperCore. The 7 search classes each hand-copied the base scraper's __init__ + context manager and had drifted (Amazon/ChatGPT/LinkedIn search lacked the env-token fallback). They now inherit one shared core: −174 lines, drift gone.

Tests: 321 passing (57 new). Version → 2.5.0.

Post-merge fix included in this release PR: test_raises_without_token was updated to mock read_cli_credentials(), since the new CLI fallback meant the test was not hermetic on machines with real brightdata login credentials present.

---

#43 — v2.4.1: X (Twitter) scraper + limit_per_input

Adds the X (Twitter) Web Scraper (client.scrape.x) — previously missing from the SDK.

• 5 variants: posts, posts_by_profile, posts_by_profiles_array, profiles, profiles_by_username (collect-by-URL and discover), each with async/sync + trigger/status/fetch.
• Adds limit_per_input to cap records per input (additive — other scrapers unchanged).
• Sync parity, tests, and a notebook walkthrough.
• Version → 2.4.1.

[artemo-brd]

Release PR: syncs main with dev, bringing in everything merged into dev since the last release (v2.4.1 on main).

Included PRs

#46 — v2.5.0: CLI-credentials auth + scraper-core dedup

Python half of the cross-SDK task "SDKs resolve credentials from the CLI store + report auth source in user-agent" (the JS half lives in sdk-js).

Before: the SDK only accepted a token via the token= parameter or the BRIGHTDATA_API_TOKEN env var — a user who had already run brightdata login still had to copy an API key by hand.

Now: with no token given, the SDK falls back to the key the CLI already saved. One login authenticates everything:

client=BrightDataClient() # zero configuration on a logged-in machine

Resolution order (first hit wins):

1. token= parameter → auth=param
2. BRIGHTDATA_API_TOKEN, then BRIGHTDATA_API_KEY env vars → auth=env
3. CLI store …/brightdata-cli/credentials.json (read-only) → auth=cli_credentials
4. Nothing found → actionable error (mentions brightdata login, the env var, and the token page)

Every request now reports how the token was obtained — making SDK onboarding measurable (feeds the sdk_auth_source Mixpanel property):

User-Agent: brightdata-sdk-python/2.5.0 (auth=cli_credentials)

Ticket checklist:

• src/brightdata/cli_credentials.py — per-platform path (Linux / macOS / Windows %APPDATA%) + read_cli_credentials() that never raises and never writes
• Same precedence in BrightDataClientandSyncBrightDataClient (sync delegates to async — pinned by test)
• Read-only: never writes into brightdata-cli/, never reads config.json (pinned by test)
• The token never appears in logs; only the source name is reported
• README Configuration: "Already logged in with the CLI? The SDK works with no configuration."
• Tests: every resolution path, precedence order, all 3 platform paths (mocked home / APPDATA), malformed / missing / empty credentials, and the no-credentials error — 25 new tests

Note: engines created by standalone scraper construction (e.g. AmazonScraper(bearer_token=...) without a client) keep today's behavior and omit the (auth=…) field — the ticket scopes the fallback to the client constructors; extending it there is a small follow-up.

Also included: Internal shared ScraperCore. The 7 search classes each hand-copied the base scraper's __init__ + context manager and had drifted (Amazon/ChatGPT/LinkedIn search lacked the env-token fallback). They now inherit one shared core: −174 lines, drift gone.

Tests: 321 passing (57 new). Version → 2.5.0.

Post-merge fix included in this release PR: test_raises_without_token was updated to mock read_cli_credentials(), since the new CLI fallback meant the test was not hermetic on machines with real brightdata login credentials present.

---

#43 — v2.4.1: X (Twitter) scraper + limit_per_input

Adds the X (Twitter) Web Scraper (client.scrape.x) — previously missing from the SDK.

• 5 variants: posts, posts_by_profile, posts_by_profiles_array, profiles, profiles_by_username (collect-by-URL and discover), each with async/sync + trigger/status/fetch.
• Adds limit_per_input to cap records per input (additive — other scrapers unchanged).
• Sync parity, tests, and a notebook walkthrough.
• Version → 2.4.1.

[artemo-brd]

Release PR: syncs main with dev, bringing in everything merged into dev since the last release (v2.4.1 on main).

Included PRs

#46 — v2.5.0: CLI-credentials auth + scraper-core dedup

Python half of the cross-SDK task "SDKs resolve credentials from the CLI store + report auth source in user-agent" (the JS half lives in sdk-js).

Before: the SDK only accepted a token via the token= parameter or the BRIGHTDATA_API_TOKEN env var — a user who had already run brightdata login still had to copy an API key by hand.

Now: with no token given, the SDK falls back to the key the CLI already saved. One login authenticates everything:

client=BrightDataClient() # zero configuration on a logged-in machine

Resolution order (first hit wins):

1. token= parameter → auth=param
2. BRIGHTDATA_API_TOKEN, then BRIGHTDATA_API_KEY env vars → auth=env
3. CLI store …/brightdata-cli/credentials.json (read-only) → auth=cli_credentials
4. Nothing found → actionable error (mentions brightdata login, the env var, and the token page)

Every request now reports how the token was obtained — making SDK onboarding measurable (feeds the sdk_auth_source Mixpanel property):

User-Agent: brightdata-sdk-python/2.5.0 (auth=cli_credentials)

Ticket checklist:

• src/brightdata/cli_credentials.py — per-platform path (Linux / macOS / Windows %APPDATA%) + read_cli_credentials() that never raises and never writes
• Same precedence in BrightDataClientandSyncBrightDataClient (sync delegates to async — pinned by test)
• Read-only: never writes into brightdata-cli/, never reads config.json (pinned by test)
• The token never appears in logs; only the source name is reported
• README Configuration: "Already logged in with the CLI? The SDK works with no configuration."
• Tests: every resolution path, precedence order, all 3 platform paths (mocked home / APPDATA), malformed / missing / empty credentials, and the no-credentials error — 25 new tests

Note: engines created by standalone scraper construction (e.g. AmazonScraper(bearer_token=...) without a client) keep today's behavior and omit the (auth=…) field — the ticket scopes the fallback to the client constructors; extending it there is a small follow-up.

Also included: Internal shared ScraperCore. The 7 search classes each hand-copied the base scraper's __init__ + context manager and had drifted (Amazon/ChatGPT/LinkedIn search lacked the env-token fallback). They now inherit one shared core: −174 lines, drift gone.

Tests: 321 passing (57 new). Version → 2.5.0.

Post-merge fix included in this release PR: test_raises_without_token was updated to mock read_cli_credentials(), since the new CLI fallback meant the test was not hermetic on machines with real brightdata login credentials present.

---

#43 — v2.4.1: X (Twitter) scraper + limit_per_input

Adds the X (Twitter) Web Scraper (client.scrape.x) — previously missing from the SDK.

• 5 variants: posts, posts_by_profile, posts_by_profiles_array, profiles, profiles_by_username (collect-by-URL and discover), each with async/sync + trigger/status/fetch.
• Adds limit_per_input to cap records per input (additive — other scrapers unchanged).
• Sync parity, tests, and a notebook walkthrough.
• Version → 2.4.1.

[artemo-brd]

Release PR: syncs main with dev, bringing in everything merged into dev since the last release (v2.4.1 on main).

Included PRs

#46 — v2.5.0: CLI-credentials auth + scraper-core dedup

Python half of the cross-SDK task "SDKs resolve credentials from the CLI store + report auth source in user-agent" (the JS half lives in sdk-js).

Before: the SDK only accepted a token via the token= parameter or the BRIGHTDATA_API_TOKEN env var — a user who had already run brightdata login still had to copy an API key by hand.

Now: with no token given, the SDK falls back to the key the CLI already saved. One login authenticates everything:

client=BrightDataClient() # zero configuration on a logged-in machine

Resolution order (first hit wins):

1. token= parameter → auth=param
2. BRIGHTDATA_API_TOKEN, then BRIGHTDATA_API_KEY env vars → auth=env
3. CLI store …/brightdata-cli/credentials.json (read-only) → auth=cli_credentials
4. Nothing found → actionable error (mentions brightdata login, the env var, and the token page)

Every request now reports how the token was obtained — making SDK onboarding measurable (feeds the sdk_auth_source Mixpanel property):

User-Agent: brightdata-sdk-python/2.5.0 (auth=cli_credentials)

Ticket checklist:

• src/brightdata/cli_credentials.py — per-platform path (Linux / macOS / Windows %APPDATA%) + read_cli_credentials() that never raises and never writes
• Same precedence in BrightDataClientandSyncBrightDataClient (sync delegates to async — pinned by test)
• Read-only: never writes into brightdata-cli/, never reads config.json (pinned by test)
• The token never appears in logs; only the source name is reported
• README Configuration: "Already logged in with the CLI? The SDK works with no configuration."
• Tests: every resolution path, precedence order, all 3 platform paths (mocked home / APPDATA), malformed / missing / empty credentials, and the no-credentials error — 25 new tests

Note: engines created by standalone scraper construction (e.g. AmazonScraper(bearer_token=...) without a client) keep today's behavior and omit the (auth=…) field — the ticket scopes the fallback to the client constructors; extending it there is a small follow-up.

Also included: Internal shared ScraperCore. The 7 search classes each hand-copied the base scraper's __init__ + context manager and had drifted (Amazon/ChatGPT/LinkedIn search lacked the env-token fallback). They now inherit one shared core: −174 lines, drift gone.

Tests: 321 passing (57 new). Version → 2.5.0.

Post-merge fix included in this release PR: test_raises_without_token was updated to mock read_cli_credentials(), since the new CLI fallback meant the test was not hermetic on machines with real brightdata login credentials present.

---

#43 — v2.4.1: X (Twitter) scraper + limit_per_input

Adds the X (Twitter) Web Scraper (client.scrape.x) — previously missing from the SDK.

• 5 variants: posts, posts_by_profile, posts_by_profiles_array, profiles, profiles_by_username (collect-by-URL and discover), each with async/sync + trigger/status/fetch.
• Adds limit_per_input to cap records per input (additive — other scrapers unchanged).
• Sync parity, tests, and a notebook walkthrough.
• Version → 2.4.1.

[artemo-brd]

Release PR: syncs main with dev, bringing in everything merged into dev since the last release (v2.4.1 on main).

Included PRs

#46 — v2.5.0: CLI-credentials auth + scraper-core dedup

Python half of the cross-SDK task "SDKs resolve credentials from the CLI store + report auth source in user-agent" (the JS half lives in sdk-js).

Before: the SDK only accepted a token via the token= parameter or the BRIGHTDATA_API_TOKEN env var — a user who had already run brightdata login still had to copy an API key by hand.

Now: with no token given, the SDK falls back to the key the CLI already saved. One login authenticates everything:

client=BrightDataClient() # zero configuration on a logged-in machine

Resolution order (first hit wins):

1. token= parameter → auth=param
2. BRIGHTDATA_API_TOKEN, then BRIGHTDATA_API_KEY env vars → auth=env
3. CLI store …/brightdata-cli/credentials.json (read-only) → auth=cli_credentials
4. Nothing found → actionable error (mentions brightdata login, the env var, and the token page)

Every request now reports how the token was obtained — making SDK onboarding measurable (feeds the sdk_auth_source Mixpanel property):

User-Agent: brightdata-sdk-python/2.5.0 (auth=cli_credentials)

Ticket checklist:

• src/brightdata/cli_credentials.py — per-platform path (Linux / macOS / Windows %APPDATA%) + read_cli_credentials() that never raises and never writes
• Same precedence in BrightDataClientandSyncBrightDataClient (sync delegates to async — pinned by test)
• Read-only: never writes into brightdata-cli/, never reads config.json (pinned by test)
• The token never appears in logs; only the source name is reported
• README Configuration: "Already logged in with the CLI? The SDK works with no configuration."
• Tests: every resolution path, precedence order, all 3 platform paths (mocked home / APPDATA), malformed / missing / empty credentials, and the no-credentials error — 25 new tests

Note: engines created by standalone scraper construction (e.g. AmazonScraper(bearer_token=...) without a client) keep today's behavior and omit the (auth=…) field — the ticket scopes the fallback to the client constructors; extending it there is a small follow-up.

Also included: Internal shared ScraperCore. The 7 search classes each hand-copied the base scraper's __init__ + context manager and had drifted (Amazon/ChatGPT/LinkedIn search lacked the env-token fallback). They now inherit one shared core: −174 lines, drift gone.

Tests: 321 passing (57 new). Version → 2.5.0.

Post-merge fix included in this release PR: test_raises_without_token was updated to mock read_cli_credentials(), since the new CLI fallback meant the test was not hermetic on machines with real brightdata login credentials present.

---

#43 — v2.4.1: X (Twitter) scraper + limit_per_input

Adds the X (Twitter) Web Scraper (client.scrape.x) — previously missing from the SDK.

• 5 variants: posts, posts_by_profile, posts_by_profiles_array, profiles, profiles_by_username (collect-by-URL and discover), each with async/sync + trigger/status/fetch.
• Adds limit_per_input to cap records per input (additive — other scrapers unchanged).
• Sync parity, tests, and a notebook walkthrough.
• Version → 2.4.1.

[artemo-brd]

Release PR: syncs main with dev, bringing in everything merged into dev since the last release (v2.4.1 on main).

Included PRs

#46 — v2.5.0: CLI-credentials auth + scraper-core dedup

Python half of the cross-SDK task "SDKs resolve credentials from the CLI store + report auth source in user-agent" (the JS half lives in sdk-js).

Before: the SDK only accepted a token via the token= parameter or the BRIGHTDATA_API_TOKEN env var — a user who had already run brightdata login still had to copy an API key by hand.

Now: with no token given, the SDK falls back to the key the CLI already saved. One login authenticates everything:

client=BrightDataClient() # zero configuration on a logged-in machine

Resolution order (first hit wins):

1. token= parameter → auth=param
2. BRIGHTDATA_API_TOKEN, then BRIGHTDATA_API_KEY env vars → auth=env
3. CLI store …/brightdata-cli/credentials.json (read-only) → auth=cli_credentials
4. Nothing found → actionable error (mentions brightdata login, the env var, and the token page)

Every request now reports how the token was obtained — making SDK onboarding measurable (feeds the sdk_auth_source Mixpanel property):

User-Agent: brightdata-sdk-python/2.5.0 (auth=cli_credentials)

Ticket checklist:

• src/brightdata/cli_credentials.py — per-platform path (Linux / macOS / Windows %APPDATA%) + read_cli_credentials() that never raises and never writes
• Same precedence in BrightDataClientandSyncBrightDataClient (sync delegates to async — pinned by test)
• Read-only: never writes into brightdata-cli/, never reads config.json (pinned by test)
• The token never appears in logs; only the source name is reported
• README Configuration: "Already logged in with the CLI? The SDK works with no configuration."
• Tests: every resolution path, precedence order, all 3 platform paths (mocked home / APPDATA), malformed / missing / empty credentials, and the no-credentials error — 25 new tests

Note: engines created by standalone scraper construction (e.g. AmazonScraper(bearer_token=...) without a client) keep today's behavior and omit the (auth=…) field — the ticket scopes the fallback to the client constructors; extending it there is a small follow-up.

Also included: Internal shared ScraperCore. The 7 search classes each hand-copied the base scraper's __init__ + context manager and had drifted (Amazon/ChatGPT/LinkedIn search lacked the env-token fallback). They now inherit one shared core: −174 lines, drift gone.

Tests: 321 passing (57 new). Version → 2.5.0.

Post-merge fix included in this release PR: test_raises_without_token was updated to mock read_cli_credentials(), since the new CLI fallback meant the test was not hermetic on machines with real brightdata login credentials present.

---

#43 — v2.4.1: X (Twitter) scraper + limit_per_input

Adds the X (Twitter) Web Scraper (client.scrape.x) — previously missing from the SDK.

• 5 variants: posts, posts_by_profile, posts_by_profiles_array, profiles, profiles_by_username (collect-by-URL and discover), each with async/sync + trigger/status/fetch.
• Adds limit_per_input to cap records per input (additive — other scrapers unchanged).
• Sync parity, tests, and a notebook walkthrough.
• Version → 2.4.1.

[artemo-brd]

Release PR: syncs main with dev, bringing in everything merged into dev since the last release (v2.4.1 on main).

Included PRs

#46 — v2.5.0: CLI-credentials auth + scraper-core dedup

Python half of the cross-SDK task "SDKs resolve credentials from the CLI store + report auth source in user-agent" (the JS half lives in sdk-js).

Before: the SDK only accepted a token via the token= parameter or the BRIGHTDATA_API_TOKEN env var — a user who had already run brightdata login still had to copy an API key by hand.

Now: with no token given, the SDK falls back to the key the CLI already saved. One login authenticates everything:

client=BrightDataClient() # zero configuration on a logged-in machine

Resolution order (first hit wins):

1. token= parameter → auth=param
2. BRIGHTDATA_API_TOKEN, then BRIGHTDATA_API_KEY env vars → auth=env
3. CLI store …/brightdata-cli/credentials.json (read-only) → auth=cli_credentials
4. Nothing found → actionable error (mentions brightdata login, the env var, and the token page)

Every request now reports how the token was obtained — making SDK onboarding measurable (feeds the sdk_auth_source Mixpanel property):

User-Agent: brightdata-sdk-python/2.5.0 (auth=cli_credentials)

Ticket checklist:

• src/brightdata/cli_credentials.py — per-platform path (Linux / macOS / Windows %APPDATA%) + read_cli_credentials() that never raises and never writes
• Same precedence in BrightDataClientandSyncBrightDataClient (sync delegates to async — pinned by test)
• Read-only: never writes into brightdata-cli/, never reads config.json (pinned by test)
• The token never appears in logs; only the source name is reported
• README Configuration: "Already logged in with the CLI? The SDK works with no configuration."
• Tests: every resolution path, precedence order, all 3 platform paths (mocked home / APPDATA), malformed / missing / empty credentials, and the no-credentials error — 25 new tests

Note: engines created by standalone scraper construction (e.g. AmazonScraper(bearer_token=...) without a client) keep today's behavior and omit the (auth=…) field — the ticket scopes the fallback to the client constructors; extending it there is a small follow-up.

Also included: Internal shared ScraperCore. The 7 search classes each hand-copied the base scraper's __init__ + context manager and had drifted (Amazon/ChatGPT/LinkedIn search lacked the env-token fallback). They now inherit one shared core: −174 lines, drift gone.

Tests: 321 passing (57 new). Version → 2.5.0.

Post-merge fix included in this release PR: test_raises_without_token was updated to mock read_cli_credentials(), since the new CLI fallback meant the test was not hermetic on machines with real brightdata login credentials present.

---

#43 — v2.4.1: X (Twitter) scraper + limit_per_input

Adds the X (Twitter) Web Scraper (client.scrape.x) — previously missing from the SDK.

• 5 variants: posts, posts_by_profile, posts_by_profiles_array, profiles, profiles_by_username (collect-by-URL and discover), each with async/sync + trigger/status/fetch.
• Adds limit_per_input to cap records per input (additive — other scrapers unchanged).
• Sync parity, tests, and a notebook walkthrough.
• Version → 2.4.1.