Metadata-Version: 2.3
Name: browser-auto-shinebed
Version: 0.1.2
Summary: AdsPower bridge wrapper for browser-act automation
Requires-Python: >=3.12, <3.13
Description-Content-Type: text/markdown

# browser-auto-shinebed

`browser-auto-shinebed` is a publishable wrapper around `browser-act` that adds
AdsPower browser mode for business teams that operate multiple stores through
AdsPower profiles.

The wrapper only connects browser-act to an AdsPower browser. It does not
reimplement page automation. After an AdsPower profile is opened, all
session-scoped browser automation commands are still handled by the original
`browser-act` session server, including `state`, `click`, `input`, `eval`,
`get`, `network`, `wait`, `tab`, `cookies`, `dialog`, `screenshot`, and upload
flows.

## Install For Another Agent

Ask the agent to install this entry Skill:

```text
Install browser-auto-shinebed.
Skill URL: https://github.com/DingShineShine/browser-auto-shinebed/tree/main/skills/browser-auto-shinebed
After installation, verify that browser-act, browser-act-skill-forge, and AdsPower bridge mode are available.
```

The entry Skill tells the agent to install this CLI package and, when needed,
the official BrowserAct Skill Forge instructions:

- `browser-act-skill-forge`: https://github.com/browser-act/skills/tree/main/browser-act-skill-forge

## Manual CLI Install

```powershell
uv tool install browser-auto-shinebed --python 3.12
browser-act doctor
browser-act --version
browser-act browser list
```

`browser-auto-shinebed` manages `browser-act-cli==1.0.6` internally. Users do
not need to install `browser-act-cli` separately. If no compatible browser-act
CLI is already available, the wrapper installs a private managed copy on first
use.

The `browser-act` command on `PATH` is expected to be this wrapper. This is the
healthy state: the wrapper preserves the original browser-act command surface
and adds AdsPower routing for `adspower:<user_id>` browser opens.

If a later manual install of `browser-act-cli` overwrites the `browser-act`
command, reinstall this package to restore wrapper ownership:

Upgrade:

```powershell
uv tool install --force browser-auto-shinebed --python 3.12
```

Default AdsPower Local API base:

```text
http://local.adspower.net:50325
```

If AdsPower requires an API key:

```powershell
$env:ADSPOWER_API_KEY="..."
```

## Usage

Open a profile directly without pre-creating a record:

```powershell
browser-act --session ads1 browser open adspower:<user_id> https://example.com
browser-act --session ads1 state
browser-act --session ads1 click 1
browser-act --session ads1 get markdown
browser-act session close ads1
```

Or create a local AdsPower browser record:

```powershell
browser-act browser create --type adspower `
  --name "ads-profile" `
  --desc "AdsPower profile for browser-act" `
  --adspower-user-id <user_id>
```

Then open it:

```powershell
browser-act --session ads1 browser open adspower:<user_id> https://example.com
```

## How It Works

Original browser-act is already CDP-based. The main difference between browser
modes is where the browser process comes from:

- `chrome`: browser-act starts a Chrome/Chromium browser.
- `chrome-direct`: browser-act connects to an existing Chrome browser.
- `stealth`: browser-act starts or connects to a stealth browser.
- `adspower`: this wrapper asks AdsPower to start a profile, then passes
  AdsPower's `ws.puppeteer` CDP endpoint to the original browser-act session
  server.

Flow:

1. `browser-act --session s browser open adspower:<user_id> <url>` is
   intercepted by this wrapper.
2. The wrapper calls AdsPower Local API `browser/start`.
3. AdsPower returns a CDP websocket such as
   `ws://127.0.0.1:<port>/devtools/browser/...`.
4. The wrapper starts a patched browser-act session server with an AdsPower
   launch driver.
5. The original browser-act session server consumes that CDP endpoint.
6. All later commands for the session run through original browser-act.

Non-AdsPower commands are delegated to `browser-act-cli==1.0.6`, loaded from
the current environment, an existing `uv tool install browser-act-cli`, or the
wrapper's private managed copy. `BROWSER_ACT_REAL_BIN` remains available as a
compatibility fallback.

## Diagnostics

```powershell
browser-act doctor
```

The doctor checks:

- whether `browser-act` is on `PATH`;
- whether `browser-act` is owned by the `browser-auto-shinebed` wrapper;
- whether the original `browser_act_cli` package can be imported;
- whether AdsPower Local API is reachable;
- how many local AdsPower bridge records are configured.

## Business Workflow Skills

This repository can also contain reusable business workflow skills. For example:

```text
https://github.com/DingShineShine/browser-auto-shinebed/tree/main/skills/wayfair-wsp-product-report
```

Those business skills should call normal `browser-act` commands. When the
session was opened with `adspower:<user_id>`, the commands automatically route
through this AdsPower bridge.
