Adding a directory channel
Contributor guide for shipping a new directory launch destination with extension autofill in OpenQuok
Connect your agent today
Draft from chat, review in your calendar, and publish only what you approve.
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:
| Pattern | Example | Notes |
|---|---|---|
| Single paid submit form | PeerPush Standard | One fixture; optional free pricing-queue variant |
| Pricing queue + premium wizard | Open Launch, TinyLaunch | Base fixture + readyUrlHint: 'pricing' variant in TS |
| Multiple independent forms | Uneed | Three fixtures; composite SQL seed module |
Note
Convention reference: Use .cursor/rules/add-directory-integration.mdc as the file-level checklist and docs/auto-launch/extension-ui-patterns.md for field mapping and manual smoke.
Identifier contract
| Concept | Format | Must align across |
|---|---|---|
| Site slug | kebab-case (peerpush, tinylaunch) | Link-directory catalog, /icons/link-directory/{slug}.svg, Add Channel tiles |
| Opportunity slug | per 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
- Member chooses a destination on My Products or the extension Directory tab.
- Backend POST /api/v1/auto-launch/submissions/intent returns startUrl, launch token, and extension_config.
- Extension opens the directory tab and shows the on-page step rail (fill / compare).
- Member edits and submits on the directory site, then marks complete in OpenQuok.
Not social OAuth
Do not add backend/integrations/providers/* entries or social composer tiles for directory-only launches. Directory connect is extension + product profile — see Platforms → Directory launch.
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>/:
| File | Purpose |
|---|---|
| config.ts | *_EXTENSION_CONFIG fixtures, *_DIRECTORY_LAUNCH_PROVIDERS (hostPatterns, contentScriptEntry, defaultStartUrl) |
| sync.ts | pricing-queue vs independent derivation rules |
| catalog.test.ts | Official 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
| Action | Path |
|---|---|
| Logo | web/static/icons/link-directory/<site>.svg |
| Add Channel tiles | web/src/lib/auto-launch/buildDirectoryAddChannelTiles.ts |
| New profilePath | businessProfileData.ts, composer validation, readiness tests |
| Operator guide | web/src/content/docs/directory-integration/<site>.md |
| Public channel page | landing 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)
- Update docs/auto-launch/extension-ui-patterns.md — destination table and smoke site count
- Add directory-integration/<site>.md and a LinkCard on Directory integration overview
- Follow Documentation contribution for MDX badges and callouts
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.
Note
Catalog-only vs SQL seed: If the site lives in link_directory_catalog_backfill.catalog.json only, run catalog backfill before the auto-launch/*_seed_*_destination.sql module — destination INSERTs join link_directory_opportunities by site and opportunity slug. If you used link-directory/504_*_seed_<site>.sql, hub rows ship in migrations; local reset applies them automatically — production still uses backfill only when you later edit JSON copy without a migration.
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 Tip
After a manual SQL delta (Option 2), you do not need the Fazier-only block from 502_*_extension_configs.sql if the destination seed already embedded extension_config. Run pnpm sync:auto-launch-configs only when fixtures changed and you need standalone UPDATEs later.
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)
| Script | Updates | Run when |
|---|---|---|
| pnpm sync:auto-launch-configs | 502_*_extension_configs.sql (UPDATE extension_config) | Fixture step JSON changed |
| pnpm sync:auto-launch-destinations | 503–507+ INSERT modules | destinationSeeds.ts or embedded config on INSERT changed |
| pnpm backend:db:backfill-link-directory-catalog | Hub link_directory_* rows from JSON | Local after reset; catalog-only sites |
| pnpm backend:db:backfill-link-directory-catalog:prod | Same against production | Before destination SQL when opportunities must exist |
| pnpm sync:auto-launch-*:check | CI / pre-PR | Ensures 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