# @dimension-studios/shop-browser

Interactive CLI and browser extension to pick a TikTok shop (authorized for your API token), load cookies from the Dimension **TTK Fetch** API, and open TikTok Seller / Affiliate sessions.

Uses the same credentials as **`@dimension-studios/ttk-proxy`**. Publishable tarball includes only compiled `dist/` and `bin/` — no database or internal monorepo code.

## Requirements

- Node.js ≥ 24 (matching the monorepo; see repo `engines`).
- Credentials for `/ttk-proxy/*` endpoints (API URL + key + secret).
- Backend support for **`GET /ttk-proxy/shops/search?q=`** (installed with the Node API that exposes TTK proxy).

## Installation (CLI users)

```bash
npm install -g @dimension-studios/shop-browser
```

Install Playwright browsers once:

```bash
pnpm exec playwright install chromium
```

If Chromium cannot launch, set `EXECUTABLE_PATH` to your Chrome/Chromium executable (documented below).

## First-time setup

Either set environment variables (e.g. in your shell profile) or persist them via the bundled config (same UX as `@dimension-studios/ttk-proxy`):

### Environment variables (recommended)

```bash
export TTK_FETCH_API_URL="https://your-node-api.example.com"
export TTK_FETCH_API_KEY="your-api-key"
export TTK_FETCH_API_SECRET="your-api-secret"
```

Then verify:

```bash
shop-browser config
```

### Save credentials with config:set

```bash
shop-browser config:set apiUrl "https://your-node-api.example.com"
shop-browser config:set apiKey "your-api-key"
shop-browser config:set apiSecret "your-api-secret"

shop-browser config --show
```

## CLI usage

Run with **no arguments** to start the flow:

```bash
shop-browser
```

1. Search for a shop by name or slug (at least **2 characters**). Results come from your token’s authorized shops only.
2. Choose a destination page (Seller Center, Affiliate Center, Support messages).
3. Close the browser window when done; the process exits.

### Optional environment

| Variable | Purpose |
|----------|--------|
| `HEADLESS` | If `true` or `1`, runs Playwright headless (default: visible window). |
| `EXECUTABLE_PATH` | Path to Chrome/Chromium if the bundled Playwright browser is not used. |
| `REMOTE_DEBUGGING_PORT` | Exposes a local Chrome DevTools endpoint on `127.0.0.1:<port>` for tools such as Chrome DevTools MCP. |

Copy `.env.example` to `.env` only for local development; do not commit real secrets.

To attach Chrome DevTools MCP to the opened browser, launch with a debugging port:

```bash
REMOTE_DEBUGGING_PORT=9222 shop-browser
```

Then configure Chrome DevTools MCP with:

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]
    }
  }
}
```

Close the browser when finished so the debugging port is no longer exposed.

### Help and version

```bash
shop-browser --help
shop-browser --version
shop-browser config --help
```

## Browser extension

The extension injects shop cookies into your existing Chrome or Firefox browser on TikTok domains (`*.tiktok.com`, `*.tiktokshop.com`, `*.tiktokglobalshop.com`).

### Build the extension (monorepo)

```bash
pnpm install
pnpm --filter @dimension-studios/shop-browser run build:extension
```

This produces:

- `packages/shop-browser/dist/extension/chrome` — unpacked Chrome extension
- `packages/shop-browser/dist/extension/firefox` — unpacked Firefox extension (for debugging)
- `packages/shop-browser/dist/extension/dimension-shop-browser.xpi` — Firefox add-on file

Extension icons are copied from `extension/icons/` (exported from `apps/app/public/icons/icon.svg`).

### Install in Chrome

1. Open `chrome://extensions`
2. Enable **Developer mode**
3. Click **Load unpacked**
4. Select `packages/shop-browser/dist/extension/chrome`

### Install in Firefox

Requires **Firefox 127** or later.

**Standard Firefox release:** Mozilla blocks unsigned add-ons on normal release builds. Use the temporary install flow below for local development, or install a signed XPI distributed through AMO or your organization. The Firefox manifest declares required data collection permissions (`authenticationInfo`, `searchTerms`) so the add-on can pass AMO validation for that signed distribution path.

**Permanent install (unsigned, special Firefox builds only):**

Use this only on Firefox **ESR**, **Developer Edition**, **Nightly**, or other **unbranded** builds where unsigned add-ons are allowed. On standard release Firefox, setting `xpinstall.signatures.required` to `false` does **not** permit a permanent unsigned install.

1. Open `about:config` and set `xpinstall.signatures.required` to `false`.
2. Open `about:addons`
3. Click the gear icon → **Install Add-on From File…**
4. Select `packages/shop-browser/dist/extension/dimension-shop-browser.xpi`

**Temporary install (recommended for standard Firefox; removed on restart):**

1. Open `about:debugging#/runtime/this-firefox`
2. Click **Load Temporary Add-on**
3. Select `packages/shop-browser/dist/extension/firefox/manifest.json`

### Extension usage

1. Build the extension with the app origin from `packages/shop-browser/.env` (`NEXT_PUBLIC_APP_URL`, or `TTK_FETCH_API_URL` as fallback).
2. Open the extension popup and click **Sign in to Dimension** if you are not already signed in on `app.dimensionstudios.co`.
3. Search for a shop (minimum **2 characters**) and select it. Results are limited to shops you can access in your current organization.
4. Turn **Auto inject** on to inject cookies when you open TikTok domains, or use **Inject now** manually.
5. Turning auto inject **off** stops future injections and leaves existing browser cookies untouched.

### IAM permission

Users need the **Use Shop Browser extension** permission (`SHOP_BROWSER_EXTENSION_ACCESS`) for each shop they inject. Organization administrators can grant it from organization-wide or shop-scoped IAM groups. This permission exposes raw TikTok shop session cookies and effectively lets the user act as an admin for that shop in their browser — grant it only to trusted users.

The CLI continues to use API URL + key + secret (`TTK_FETCH_API_*`); only the browser extension uses SaaS session cookies.

### CI/CD release

The extension is built and published automatically when `@dimension-studios/shop-browser` is released via [semantic-release](https://github.com/semantic-release/semantic-release) on `main-release`.

**What CI does**

1. Bumps the npm package version (same release as the CLI).
2. Builds the extension with `NEXT_PUBLIC_APP_URL` from GitHub Actions vars (wired in `.github/workflows/release.yml`). The extension manifest version comes from `@dimension-studios/shop-browser` `package.json` (aligned with the semantic-release version on CI).
3. Attaches release artifacts to the GitHub Release:
   - `dimension-shop-browser.xpi` — Firefox add-on
   - `dimension-shop-browser-chrome.zip` — Chrome unpacked extension (upload to Chrome Web Store or load unpacked)

**Required GitHub configuration**

- Repository variable: `NEXT_PUBLIC_APP_URL` (e.g. `https://app.dimensionstudios.co` for production releases).

**Install from a release**

1. Open the [GitHub Releases](https://github.com/dimension-studios/dimension/releases) page for this repo.
2. Download the XPI or Chrome ZIP from the latest `@dimension-studios/shop-browser` release.
3. **Firefox:** install the XPI (signed AMO distribution still requires a separate Mozilla submission).
4. **Chrome:** upload the ZIP to the [Chrome Web Store developer dashboard](https://chrome.google.com/webstore/devconsole), or unzip and load unpacked for internal testing.

CI also runs `pnpm run build:extension` on every pull request (`.github/workflows/check.yml`) to catch build regressions early.

### Automatic store listing (Chrome + Firefox)

On **`main-release`** only, after a successful semantic-release, CI submits the built extension to:

- **Chrome Web Store** — upload + publish via `chrome-webstore-upload-cli`
- **Firefox Add-ons (AMO)** — listed submission via `web-ext sign` (submission API is default in web-ext 8+)

#### One-time developer setup

**Chrome Web Store**

1. Create the extension item in the [Chrome Web Store developer dashboard](https://chrome.google.com/webstore/devconsole) (first upload can be manual).
2. Enable the [Chrome Web Store API](https://developer.chrome.com/docs/webstore/using-api) on a Google Cloud project.
3. Create OAuth credentials and generate a refresh token — [chrome-webstore-upload-keys](https://github.com/fregante/chrome-webstore-upload-keys) walks through this.
4. Note your **Publisher ID** (developer dashboard) and **Extension ID** (from the listing URL or `chrome://extensions` when loaded unpacked).

**Firefox Add-ons**

1. Create the add-on on [addons.mozilla.org](https://addons.mozilla.org/developers/) (listed).
2. Generate **JWT API credentials** (issuer + secret) from the developer hub.
3. The extension ID is already set in `extension/manifest.firefox.json`: `dimension-shop-browser@dimensionstudios.co`.

#### GitHub secrets (repository)

| Secret | Description |
|--------|-------------|
| `SHOP_BROWSER_CHROME_EXTENSION_ID` | Chrome extension ID (32-char string) |
| `SHOP_BROWSER_CHROME_PUBLISHER_ID` | Chrome Web Store publisher ID |
| `SHOP_BROWSER_CHROME_CLIENT_ID` | Google OAuth client ID |
| `SHOP_BROWSER_CHROME_CLIENT_SECRET` | Google OAuth client secret (plain `GOCSPX-…` value from Google Cloud) |
| `SHOP_BROWSER_CHROME_REFRESH_TOKEN` | Google OAuth refresh token |
| `SHOP_BROWSER_AMO_JWT_ISSUER` | AMO JWT issuer (`user:…`) |
| `SHOP_BROWSER_AMO_JWT_SECRET` | AMO JWT secret |

If any store secret is missing, that store is skipped (release still succeeds). Both stores require all of their respective secrets to be set.

#### Manual store publish (local)

After building with production `NEXT_PUBLIC_APP_URL`:

```bash
export NEXT_PUBLIC_APP_URL=https://app.dimensionstudios.co
pnpm --filter @dimension-studios/shop-browser run build:extension

# Set the same SHOP_BROWSER_* secrets as in GitHub, then:
pnpm --filter @dimension-studios/shop-browser run publish:stores
```

New versions enter each store’s review queue after submission; approval is handled by Google/Mozilla.

## Development (in this monorepo)

```bash
pnpm install
pnpm --filter @dimension-studios/shop-browser run build
pnpm --filter @dimension-studios/shop-browser run build:extension
pnpm --filter @dimension-studios/shop-browser run type-check
```

Run CLI from source (expects env via `dotenv` / linked root `.env`):

```bash
pnpm --filter @dimension-studios/shop-browser run start
# or from repo root:
pnpm run tools:isb
```

Rebuild the extension after popup/background changes:

```bash
pnpm --filter @dimension-studios/shop-browser run dev:extension
```

Then reload the unpacked extension in your browser.

## Related packages

- **`@dimension-studios/ttk-proxy`** — call TTK proxy APIs from the terminal, including `ttk-proxy shops <query>` for debugging shop search.

## License

ISC

## Author

Dimension Studios