Skip to main content

Browser Extension (Dev)

Build the Chrome (MV3) browser extension for Subscriberbot from source.

Repository​

git clone https://github.com/algoshred/subscriberbot-browser-extension.git
cd subscriberbot-browser-extension

Development​

bun install
bun run dev              # watch build
bun run build:dev        # single development build
bun run lint             # ESLint
bun run lint:fix         # fix ESLint issues
bun run type-check       # TypeScript
bun run format           # Prettier
bun run format:check     # Prettier check
bun run test             # unit tests
bun run test:watch       # unit tests in watch mode
bun run test:coverage    # unit tests with coverage
bun run test:smoke       # production-build smoke check
bun run zip              # build + create extension.zip
bun run sanity           # format:check + lint + type-check + build + test + smoke

Architecture​

  • src/background.ts — service worker; the only place that calls the API.
  • src/api/* — one module per Subscriberbot entity, with GraphQL strings that match the real wspace-subscriberbot-svc schema.
  • src/api/graphql/client.ts — dual-header authenticated client with retry, exponential backoff, and 429 handling.
  • src/api/auth/* — OAuth2 device-code + workspace-token issuance.
  • src/ui/{popup,options,sidepanel} — the three UI surfaces.
  • src/core/env.ts — single source of truth for environment/endpoint resolution.

Authentication​

OAuth2 device-code flow against the global gateway with client id burdenoff_cli_subscriberbot. After sign-in the user selects a workspace; issueWorkspaceToken mints a workspace-scoped token. Workspace queries send both headers:

  • Authorization: Bearer <platform token>
  • X-Workspace-Authorization: Bearer <workspace token>

Testing​

Unit tests mock chrome.storage.local and fetch so every backend API call made by the extension is exercised without network access. API module tests live under tests/api/ and verify that each GraphQL root field is called with the correct variables and dual-header workspace auth.

The production-build smoke check (bun run test:smoke) rebuilds the extension with default prod settings and asserts that all required files are present, manifest.json is valid, no localhost permissions remain, and the prod gateway endpoints are baked into the background bundle.

Releasing​

Tag pushes build the extension and attach a zip to a GitHub Release. Uploading to the Chrome Web Store is human-gated — it only runs on a manual workflow_dispatch. See RELEASE.md.

Environment selection

The extension targets production by default. Use the BURDENOFF_ENV environment variable at build time to switch gateways:

EnvCommandWorkspace gatewayGlobal gateway
prodbun run buildhttps://graphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://graphql.burdenoff.com/global/graphql
alphaBURDENOFF_ENV=alpha bun run buildhttps://alphagraphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://alphagraphql.burdenoff.com/global/graphql
localBURDENOFF_ENV=local bun run build:devhttp://localhost:4003/workspaces/graphqlhttp://localhost:4000/global/graphql

When BURDENOFF_ENV is omitted, the build defaults to prod and the production manifest strips all localhost host_permissions so the Chrome Web Store review sees only the required production URLs.