Skip to main content

Browser Extension

The Chrome (MV3) browser extension for HeadshotMarketing. Manage providers, offerings, orders, reviews, and campaign KPIs directly from your browser, backed by the HeadshotMarketing GraphQL gateways.

Features​

  • Popup — quick KPIs (active campaigns, pending orders, revenue), top providers, and recent orders, plus a service-health dot.
  • Side panel (Ctrl+Shift+H) — a tabbed dashboard:
    • Campaigns — filter by status, drill into a campaign.
    • Contacts — manage contacts and their status.
    • Leads — track and advance leads.
    • Deals — track deals through pipelines.
    • Social — social posts and publishing status.
  • Options — configure gateway endpoints + OAuth2 client id and theme.
  • Auth — Burdenoff SSO via the OAuth2 device-code flow (client id burdenoff_cli_headshotmarketing); workspace-scoped tokens for every request.

Install​

The extension is available from the Chrome Web Store (search for "HeadshotMarketing"). For local development, load the unpacked extension:

git clone https://github.com/Algoshred/headshotmarketing-browser-extension.git
cd headshotmarketing-browser-extension
bun install
bun run build        # production build → dist/

Load dist/ as an unpacked extension at chrome://extensions (Developer mode).

Environment selection​

The active gateway environment is selected at build time via the BURDENOFF_ENV environment variable. Production builds default to prod so the extension never ships with localhost endpoints.

EnvCommandWorkspace gatewayGlobal gateway
prodbun run build (default)https://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 devhttp://localhost:4003/workspaces/graphqlhttp://localhost:4000/global/graphql

The default endpoints are resolved by src/core/env.ts — the only file in the repo that hardcodes gateway URLs.

Development​

bun install
bun run dev          # watch build for development
bun run build        # production build
bun run sanity       # format:check + lint + type-check + build + test + smoke:build

Testing​

All backend API calls are covered with mock-based Jest tests.

bun run test              # run all tests
bun run test:coverage     # with coverage report
bun run smoke:build       # production build smoke check

Architecture​

  • src/background.ts — service worker; the only place that calls the API.
  • src/core/env.ts — single source of truth for default gateway endpoints.
  • src/api/* — one module per HeadshotMarketing entity, with GraphQL strings that match the real wspace-headshotmarketing-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.

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.

Last updated on