ContextQMD
Back to Twenty

twenty-partners

packages/twenty-apps/internal/twenty-partners/README.md

2.8.04.3 KB
Original Source

twenty-partners

A Twenty app that turns the CRM into the operating system for the Twenty partner program: intake partner-eligible deals, match them to vetted marketplace partners, and track the matching pipeline end-to-end.

Built on Twenty with twenty-sdk v2.5.

What's inside

  • Custom object: Partner — slug, status, availability, served geos, languages spoken, deployment expertise, Calendly link, last-match timestamp. See src/objects/partner.object.ts.
  • Opportunity extensions — matchStatus, designDocStatus, introSentAt, lastRelanceSentAt, tftId, plus a partner relation.
  • Logic functions
    • on-opportunity-auto-match — fires when matchStatus is set to AUTO_MATCH. Assigns the longest-idle available partner and flips status to MATCHED. If no partner is available, hands off to MANUAL_MATCH with an audit Note explaining why.
    • list-available-partners — surfaces matchable partners for a given opportunity.
    • post-install — first-run setup.
  • Roles (src/roles/)
    • Twenty Partner Ops — internal team role, full CRUD on Partner/Company/Person/Opportunity.
    • Partner — placeholder external-partner role. Do not assign until Twenty ships row-level permissions — it currently grants access to every record.
  • Views (src/views/)
    • Waiting for match — opportunities awaiting human action (matchStatus is TO_BE_MATCHED or MANUAL_MATCH).
    • Matches overview — full matching funnel grouped by matchStatus (configure Kanban grouping manually in the UI).
    • Opportunities — replacement of the native opportunities view with the partner columns.
    • Partners and All matched deals — partner-side index and deal log.
  • Sidebar nav — surfaced in workflow order: Waiting for match, All partner deals, Matches overview, Partners, Opportunities.
  • Seed scripts (src/scripts/) — populate a fresh workspace with realistic demo data.

Match status pipeline

matchStatus is a non-nullable SELECT field with a default of TO_BE_MATCHED. The 10 states follow the deal lifecycle:

StatusMeaning
TO_BE_MATCHEDDefault — deal entered, awaiting assignment
MANUAL_MATCHNeeds a human to pick a partner
AUTO_MATCHTriggers automatic partner assignment
MATCHEDPartner assigned
INTRODUCED_TO_A_PARTNERCustomer intro sent
WORKING_WITH_A_PARTNEREngagement underway
IMPLEMENTINGActive implementation
WONDeal closed won
RECONNECT_LATERPaused — reconnect in future
LOSTDeal closed lost

Getting started

Requires a local Twenty server at http://localhost:2020 and Node ^24.5.

bash
yarn install
yarn twenty dev

Default dev credentials: [email protected] / [email protected].

Run yarn twenty help for the full CLI reference.

Common commands

CommandWhat it does
yarn twenty devStart the dev server and sync the app on file changes
yarn twenty server statusCheck the local Twenty server
yarn lint / yarn lint:fixRun oxlint
yarn testRun integration tests (vitest.config.ts)

Seeding demo data

Two idempotent seed scripts. Both run via the vitest.seed.config.ts config that skips the global app uninstall/reinstall.

bash
# 1. Marketplace partners (run first — pipeline seed wires opportunities to these by slug)
yarn vitest run --config vitest.seed.config.ts src/scripts/seed-marketplace-partners.ts

# 2. Pipeline demo: 3 companies, 3 people, 15 opportunities spread across matchStatus values
yarn vitest run --config vitest.seed.config.ts src/scripts/seed-pipeline-demo.ts

Both scripts skip records that already exist (by slug, name, or firstName+lastName), so they are safe to re-run.

Known limitations

Current SDK gaps blocking further polish:

  • Custom Partner record page layout (RECORD_TABLE has no relation scoping).
  • Native Opportunities view column-order override.
  • Kanban view configuration from app code (ViewType.KANBAN is currently ignored).
  • App and field descriptions.

Learn more