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

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.

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:

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)

npm install
npm run build:extension -w @dimension-studios/shop-browser

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 on main-release / preprod-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 npm 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+)

Preprod (preprod-release) still publishes GitHub Release artifacts but does not auto-list on stores.

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)

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

export NEXT_PUBLIC_APP_URL=https://app.dimensionstudios.co
npm run build:extension -w @dimension-studios/shop-browser

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

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

Development (in this monorepo)

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

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

Rebuild the extension after popup/background changes:

npm run dev:extension -w @dimension-studios/shop-browser

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