@dimension-studios/shop-browser

Interactive CLI to pick a TikTok shop (authorized for your API token), load cookies from the Dimension TTK Fetch API, open Chromium with Playwright, and navigate to common TikTok Seller / Affiliate URLs.

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)

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

Install Playwright browsers once:

npx 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)

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:

shop-browser config

Save credentials with config:set

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

Usage

Run with no arguments to start the flow:

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. |

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

Help and version

shop-browser --help
shop-browser --version
shop-browser config --help

Development (in this monorepo)

npm install
npm run build -w @dimension-studios/shop-browser
npm run type-check -w @dimension-studios/shop-browser

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

npm run start -w @dimension-studios/shop-browser
# or from repo root:
npm run tools:isb

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