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

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

Install Chromium with the Playwright version bundled in the package (a bare bunx playwright pulls the latest Playwright, which downloads a different Chromium build):

# npm global install
node "$(npm root -g)/@dimension-studios/shop-browser/node_modules/playwright-core/cli.js" install chromium
# bun global install (bun add -g)
bun ~/.bun/install/global/node_modules/playwright-core/cli.js install chromium

Run it again after updating shop-browser when it fails with Executable doesn't exist at …/ms-playwright/chromium-<build>/…: a new release can bump Playwright and expect a newer build.

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

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

Add -i / --allow-invalid to open a shop whose stored cookie is no longer marked valid (disabled shop, expired login):

shop-browser --allow-invalid

Optional environment

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:

REMOTE_DEBUGGING_PORT=9222 shop-browser

Then configure Chrome DevTools MCP with:

{
  "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

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)

bun install
bun run --cwd tools/shop-browser build:extension

This produces:

• tools/shop-browser/dist/extension/chrome — unpacked Chrome extension
• tools/shop-browser/dist/extension/firefox — unpacked Firefox extension (for debugging)
• tools/shop-browser/dist/extension/dimension-shop-browser.xpi — Firefox add-on file
• tools/shop-browser/dist/extension/dimension-shop-browser-chrome.zip — zipped Chrome extension

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 tools/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 tools/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 tools/shop-browser/dist/extension/firefox/manifest.json

Extension usage

1. Build the extension with the app origin from tools/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 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 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, or unzip and load unpacked for internal testing.

CI also runs bun run --cwd tools/shop-browser 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 (first upload can be manual).
2. Enable the Chrome Web Store API on a Google Cloud project.
3. Create OAuth credentials and generate a refresh token — 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 (listed).
2. Generate JWT API credentials (issuer + secret) from the developer hub.
3. The extension ID is already set in extension/manifest.firefox.json: [email protected].

GitHub secrets (repository)

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:

export NEXT_PUBLIC_APP_URL=https://app.dimensionstudios.co
bun run --cwd tools/shop-browser build:extension

# Set the same SHOP_BROWSER_* secrets as in GitHub, then:
bun run --cwd tools/shop-browser publish:stores

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

Development (in this monorepo)

bun install
bun run --cwd tools/shop-browser build
bun run --cwd tools/shop-browser build:extension
bun run --cwd tools/shop-browser type-check

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

bun run --cwd tools/shop-browser start
# or from repo root:
bun run tools:isb

Rebuild the extension after popup/background changes:

bun run --cwd tools/shop-browser 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