Skip to content

Adding a directory channel

Contributor guide for shipping a new directory launch destination with extension autofill in OpenQuok

6 min read

Connect your agent today

Draft from chat, review in your calendar, and publish only what you approve.

Start your free trial

Overview

A directory channel is not a social SocialProvider. Members keep a product profile in OpenQuok, open the directory site in Chrome, and use the browser extension to autofill forms. OpenQuok does not submit listings on their behalf.

Each shipped destination is one provider slug (for example peerpush-standard-launch) with:

  • Rows in auto_launch_destinations (start URL, published flag, optional link-directory opportunity)
  • Typed extension_config JSON (steps, fields, selectors, proof rules)
  • Extension content scripts + side panel handoff

Pick reference sites by shape:

PatternExampleNotes
Single paid submit formPeerPush StandardOne fixture; optional free pricing-queue variant
Pricing queue + premium wizardOpen Launch, TinyLaunchBase fixture + readyUrlHint: 'pricing' variant in TS
Multiple independent formsUneedThree fixtures; composite SQL seed module

Identifier contract

ConceptFormatMust align across
Site slugkebab-case (peerpush, tinylaunch)Link-directory catalog, /icons/link-directory/{slug}.svg, Add Channel tiles
Opportunity slugper tier (standard-launch, premium-launch)link_directory_opportunities.slug
Provider slug{site}-{variant}DB, destination-configs, extension registration, tests

Wire opportunities with auto_launch_enabled and auto_launch_provider_slug. Use picker_group_key when one Add Channel card exposes multiple variants.

End-to-end flow

  1. Member chooses a destination on My Products or the extension Directory tab.
  2. Backend POST /api/v1/auto-launch/submissions/intent returns startUrl, launch token, and extension_config.
  3. Extension opens the directory tab and shows the on-page step rail (fill / compare).
  4. Member edits and submits on the directory site, then marks complete in OpenQuok.

Contributor checklist

1. Catalog and migrations

Add link-directory site + opportunities (SQL under backend/supabase/db/link-directory/ or hub catalog backfill JSON when the site is catalog-only — see existing TinyLaunch wiring).

Register auto-launch destination rows in common/src/auto-launch/destination-configs/destinationSeeds.ts (next tier-507+ SQL filename, stable destination UUIDs, start_url, opportunity slug).

Run code generation — do not hand-edit generated JSON blobs:

pnpm common:build
pnpm sync:auto-launch-configs
pnpm sync:auto-launch-destinations
pnpm backend:db:aggregate-migrations-all

Apply migrations on your local Supabase so provider_slug resolves (extension side panel “destination not found” usually means the row is missing locally).

Catalog-only sites (TinyLaunch, Fazier, …): opportunities are not re-inserted on supabase db reset — run the local backfill after reset (see Rollout).

Tier order: 502_*_extension_configs.sql (UPDATE configs) before 503–507+ destination INSERT modules.

2. TypeScript fixtures (destination-configs)

Per site under common/src/auto-launch/destination-configs/sites/<site>/:

FilePurpose
config.ts*_EXTENSION_CONFIG fixtures, *_DIRECTORY_LAUNCH_PROVIDERS (hostPatterns, contentScriptEntry, defaultStartUrl)
sync.tspricing-queue vs independent derivation rules
catalog.test.tsOfficial category/tag/select labels when the form uses catalogs

Register in destination-configs/index.ts (DIRECTORY_EXTENSION_CONFIG_FIXTURES), directoryLaunchRegistry.ts, and fieldCatalogRegistry.ts when fields use catalogs.

Pricing-queue variant: second slug’s fixture = { ...base, readyUrlHint: 'pricing' }; destination start_url points at pricing; validators in extensionConfigDerivation.ts enforce parity.

3. Browser extension

  • Thin entry: extension/src/content/directory-launch/<site>-host.ts → registerDirectoryLaunchProvider('…')
  • extension/scripts/build-extension.mjs + extension/manifest.json `content_scripts` and `host_permissions`
  • Site login adapter: extension/src/directory/directory-launch/siteLogin/<site>.ts + register in detectDirectorySiteLogin.ts
  • Extend readFormField.ts / fillEngine.ts + tests when DOM does not match existing selectors

Build: pnpm common:build && pnpm --filter @openquok/browser-extension build, then load extension/dist/ unpacked.

4. Web dashboard and marketing

ActionPath
Logoweb/static/icons/link-directory/<site>.svg
Add Channel tilesweb/src/lib/auto-launch/buildDirectoryAddChannelTiles.ts
New profilePathbusinessProfileData.ts, composer validation, readiness tests
Operator guideweb/src/content/docs/directory-integration/<site>.md
Public channel pagelanding data + /channels/{slug} when the site is marketed

Backend API surface is usually unchanged (AutoLaunchRoute already serves intents). Extend AutoLaunchService.unit.test.ts only when behavior changes.

5. Documentation (same PR)

Rollout: local and production

Run these in order after your PR merges (or on a branch-linked staging DB). Full production context: Production — Supabase migrations. Catalog CLI details: Catalog backfill.

Local (after supabase db reset or fresh clone)

From the repo root:

pnpm common:build
pnpm sync:auto-launch-configs
pnpm sync:auto-launch-destinations
pnpm backend:db:aggregate-migrations-all

From backend/:

supabase db reset

Catalog-only site — restore hub rows (replace <site-slug>):

pnpm backend:db:backfill-link-directory-catalog -- --dry-run --slug <site-slug>
pnpm backend:db:backfill-link-directory-catalog -- --slug <site-slug>

Optional dev user (skip browser signup): pnpm backend:db:bootstrap-local-dev-user — see First setup as super admin.

Build and load the extension, then manual smoke per extension-ui-patterns.md.

Production — apply database changes

Use <YYYYMMDD> from the current backend/supabase/migrations/*_core_structure.sql filename (date segment only).

A. Catalog-only or JSON copy change — run first when the site is JSON-backed or you changed hub opportunities:

pnpm backend:db:backfill-link-directory-catalog:prod -- --dry-run --slug <site-slug>
pnpm backend:db:backfill-link-directory-catalog:prod -- --slug <site-slug> --force

Use --force when rows already exist (editorial updates). Requires backend/.env.production.local.

B. Destination rows + extension_config — apply your site’s module, for example backend/supabase/db/auto-launch/507_20261120_seed_fazier_destination.sql (run the entire file in Supabase SQL Editor), or CLI push:

cd backend
pnpm db:production:push-db:dry-run
pnpm db:production:push-db

C. Sync migration history — after Option 2 (SQL Editor) or when history lags schema:

cd backend
npx supabase@latest migration repair <YYYYMMDD> --status applied --remote
pnpm db:production:migration-list

D. Deploy app surfaces when code changed (from repo root):

pnpm vercel:deploy:backend:prod
pnpm vercel:deploy:web:prod

Publish the Chrome extension when content scripts or manifest hosts changed — API/DB alone does not update members’ browsers.

Hub/API cache may lag a few minutes after catalog backfill when caching is enabled; see Catalog backfill.

Sync scripts (when to run what)

ScriptUpdatesRun when
pnpm sync:auto-launch-configs502_*_extension_configs.sql (UPDATE extension_config)Fixture step JSON changed
pnpm sync:auto-launch-destinations503–507+ INSERT modulesdestinationSeeds.ts or embedded config on INSERT changed
pnpm backend:db:backfill-link-directory-catalogHub link_directory_* rows from JSONLocal after reset; catalog-only sites
pnpm backend:db:backfill-link-directory-catalog:prodSame against productionBefore destination SQL when opportunities must exist
pnpm sync:auto-launch-*:checkCI / pre-PREnsures SQL matches TS

Source of truth for destination rows is destinationSeeds.ts; for extension_config shape is sites/*/config.ts.

Reference implementations

Verification before PR

  • pnpm --filter openquok-common test:unit (includes destination-configs.test.ts sync --check)
  • pnpm --filter @openquok/browser-extension test when extension fill/read logic changed
  • Manual smoke per extension-ui-patterns.md — sign in on extension, pick channel avatar, handoff, fill on live site
  • No secrets or third-party project names in comments (source neutrality)
  • Do not edit aggregated *_core_structure.sql directly
Search documentation
Find a docs page
Discord Support