Typed tooling for the Twenty CRM. A REST client your services and agents can call, the lead pipeline declared as a Twenty App, and typed events when a lead moves.
Twenty is an open-source CRM with a good API. This repo is what we built so the rest of our software could use it as the one place relationship records live: an inbox that files a new contact, an app that opens an Opportunity when it finds a lead, an agent that looks a person up by phone number.
| Part | Use it when |
|---|---|
@practicalworks/crm |
You want typed, tested calls for companies, people, notes, tasks and opportunities, behind one CrmPort interface you can fake in tests. It looks people up by email or phone the way an inbox needs, and stores North American phone numbers the way Twenty expects them. |
twenty-app/ |
You want your pipeline's shape in code review, not hand-made in settings: custom objects and fields, select options and views, applied with Twenty's app tooling. It also sends crm/opportunity.* events to Inngest when a lead opens, moves or closes. |
npm install @practicalworks/crmimport { CrmClient } from "@practicalworks/crm";
const crm = new CrmClient({
baseUrl: "https://crm.example.com",
apiKey: process.env.TWENTY_API_KEY!, // Settings → APIs & Webhooks in Twenty
});
const [person] = await crm.findPeople({ phone: "(813) 555-0142" });
const [company] = await crm.searchCompanies("Harbor");The package README covers every call, the types and the opportunity events.
- Provenance on every release. Versions are published from this repo's
mainby GitHub Actions through npm trusted publishing, with no long-lived token. The job checks the registry's provenance attestation before it passes, and you can check it yourself withnpm audit signatures. - Nothing private in the repo.
pnpm guardfails CI on credentials, instance hostnames, internal references or brand data. - The app is planned on every pull request and applied only by hand.
.github/workflows/twenty-app.ymlrunstwenty app planon each PR. Applying needs a confirmed manual dispatch: stage options first, thentwenty app apply --no-prune.
pnpm install
pnpm guard && pnpm build && pnpm typecheck && pnpm testTo try the app against your own workspace (Node 24, with TWENTY_API_URL and TWENTY_API_KEY set): node twenty-app/scripts/stage-options.ts (a dry run), then twenty app plan --path twenty-app --no-prune.
To release, bump packages/client/package.json version; merging to main publishes it.
Issues and pull requests are welcome. Please open an issue before a large change. Report a vulnerability privately through GitHub's security advisories.
Practical Works, a small software shop in Tampa Bay. Twenty is our CRM, and every app we run writes to it through this client, so we maintain it because we depend on it.
Questions, bug reports and ideas are welcome in issues. And if you need a hand shipping an app or wiring your systems into a CRM, we take on projects.
MIT licensed.