@byduty/crm-app

AGPL-3.0 — see LICENSE Status: Phase 2 scaffold (pre-alpha) Upstream: https://github.com/byduty/crm-app Parent platform: https://byduty.com

Twenty CRM integration package for the ByDuty security-operations platform. Installs into a Twenty workspace via Twenty's Apps framework. Declares ByDuty-native objects (Site, Guard, Shift, Contract, Incident, ComplianceViolation) alongside Twenty's standard Company/Person/Opportunity, ships field extensions that carry ByDuty foreign keys, exposes widgets that render ByDuty operational data inside Twenty, and routes sync traffic between the two systems.

Architecture note — why this is a separate repo

This package sits in Zone B of a three-zone license boundary. Zone A is the closed-source ByDuty monorepo (github.com/byduty/byduty); Zone C is an unmodified twentycrm/twenty Docker image. Zone B imports twenty-sdk (AGPL-3.0) and is therefore AGPL-3.0 itself.

The monorepo never imports twenty-sdk — CI in byduty/byduty enforces that via .github/workflows/license-boundary.yml. All traffic between Zone A and Zone B flows over HTTPS (webhooks, widget API calls, launch tokens). That network boundary is what keeps the ByDuty proprietary codebase free of AGPL obligations. See the upstream blueprint at docs/TWENTY_CRM_INTEGRATION_BLUEPRINT.md §1.3 for the full legal reasoning.

What's in the package

manifest.config.ts                   — defineApplication entry point
src/
├── constants/
│   └── universal-identifiers.ts     — stable UUIDs (never change after publish)
├── roles/
│   └── byduty-integration.role.ts   — least-privilege default role
├── objects/                         — custom objects (Phase 2+ fan-out)
│   └── site.object.ts               — first reference implementation
├── fields/                          — Twenty standard-object field extensions
│   └── company-byduty-client-id.field.ts
└── functions/                       — sync traffic routes + triggers
    ├── on-opportunity-won.trigger.ts
    └── sync-client-from-byduty.http-route.ts

Install into a Twenty workspace

Not yet published. Post-publish (Phase 2 exit):

# From a Twenty workspace admin's dev machine:
yarn twenty install @byduty/crm-app@<version>

Develop locally

yarn install
yarn typecheck          # tsc --noEmit — catches shape errors
yarn build              # yarn twenty build — validates manifest

Environment variables this app reads at install time

Variable	Purpose	Required
BYDUTY_API_URL	ByDuty REST/GraphQL base, e.g. https://api.byduty.com	yes
BYDUTY_WEBHOOK_SECRET	HMAC secret for outbound webhooks from ByDuty (must match TWENTY_WEBHOOK_SECRET in ByDuty)	yes

Publishing

Publishing is automated via .github/workflows/publish.yml on tag push:

# Maintainer flow
yarn version patch      # or minor / major
git push --follow-tags
# → GitHub Action runs `npm publish --access public` with NPM_TOKEN repo secret

Contributing

This is AGPL-3.0 public code. PRs welcome. All commits must stay within the Zone B scope — no closed-source business logic, no ByDuty secrets, no pricing/compliance rules. Anything that belongs in ByDuty proper goes to the private monorepo instead.

License notice

Copyright (C) 2026 ByDuty, Inc.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

Acknowledgments

Built on Twenty CRM (Twenty Labs, PBC). Twenty is also AGPL-3.0 — source at the linked repo.