@growthub/cli 0.3.54 → 0.3.55

package/assets/worker-kits/growthub-twenty-crm-v1/bundles/growthub-twenty-crm-v1.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": 2,
+  "bundle": {
+    "id": "growthub-twenty-crm-v1",
+    "version": "1.0.0",
+    "kitId": "growthub-twenty-crm-v1",
+    "workerId": "twenty-crm-operator"
+  },
+  "briefType": "twenty-crm-growth-stack",
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "requiredFrozenAssets": [
+    "QUICKSTART.md",
+    ".env.example",
+    "skills.md",
+    "output-standards.md",
+    "runtime-assumptions.md",
+    "validation-checklist.md",
+    "workers/twenty-crm-operator/CLAUDE.md",
+    "brands/_template/brand-kit.md",
+    "brands/growthub/brand-kit.md",
+    "brands/NEW-CLIENT.md",
+    "setup/clone-fork.sh",
+    "setup/verify-env.mjs",
+    "setup/check-deps.sh",
+    "output/README.md",
+    "templates/crm-setup-brief.md",
+    "templates/data-model-design.md",
+    "templates/lead-enrichment-pipeline.md",
+    "templates/pipeline-automation-brief.md",
+    "templates/webhook-integration-spec.md",
+    "templates/api-query-plan.md",
+    "templates/crm-playbook.md",
+    "templates/custom-object-design.md",
+    "templates/import-mapping.md",
+    "templates/workspace-config-checklist.md",
+    "templates/integration-handoff.md",
+    "templates/enrichment-field-map.md",
+    "examples/crm-setup-sample.md",
+    "examples/lead-enrichment-sample.md",
+    "examples/pipeline-automation-sample.md",
+    "examples/crm-playbook-sample.md",
+    "docs/twenty-fork-integration.md",
+    "docs/api-and-webhooks.md",
+    "docs/data-model-layer.md",
+    "growthub-meta/README.md",
+    "growthub-meta/kit-standard.md"
+  ],
+  "optionalPresets": [],
+  "export": {
+    "folderName": "growthub-agent-worker-kit-twenty-crm-v1",
+    "zipFileName": "growthub-agent-worker-kit-twenty-crm-v1.zip"
+  },
+  "activationModes": ["export"]
+}

package/assets/worker-kits/growthub-twenty-crm-v1/docs/api-and-webhooks.md

@@ -0,0 +1,296 @@
+# API and Webhooks — Twenty CRM
+
+**Kit:** `growthub-twenty-crm-v1`
+
+---
+
+## OVERVIEW
+
+Twenty CRM exposes two API surfaces:
+
+1. **GraphQL API** at `<TWENTY_API_URL>/graphql` — the primary data access surface for queries and mutations
+2. **REST API** at `<TWENTY_API_URL>/api/objects/<object-name>` — simpler CRUD operations
+
+Both require a Bearer token authentication header.
+
+---
+
+## AUTHENTICATION
+
+```
+Authorization: Bearer <TWENTY_API_TOKEN>
+Content-Type: application/json
+```
+
+Tokens are workspace-scoped and generated in:
+**Settings > API > Tokens > Generate API Token**
+
+---
+
+## GRAPHQL API
+
+### Endpoint
+
+```
+POST <TWENTY_API_URL>/graphql
+```
+
+### Common query patterns
+
+#### List all People
+
+```graphql
+query {
+  people {
+    edges {
+      node {
+        id
+        name { firstName lastName }
+        emails { primaryEmail }
+        position
+        company { name domain }
+        createdAt
+      }
+    }
+    totalCount
+  }
+}
+```
+
+#### Filter People by email domain
+
+```graphql
+query {
+  people(filter: {
+    emails: { primaryEmail: { like: "%@acme.com" } }
+  }) {
+    edges {
+      node {
+        id
+        name { firstName lastName }
+        emails { primaryEmail }
+      }
+    }
+  }
+}
+```
+
+#### Get open Opportunities by stage
+
+```graphql
+query {
+  opportunities(filter: {
+    stage: { in: ["LEAD", "QUALIFIED", "DEMO", "PROPOSAL"] }
+  }, orderBy: { closeDate: AscNullsLast }) {
+    edges {
+      node {
+        id
+        name
+        stage
+        amount { amountMicros currencyCode }
+        closeDate
+        assignee { name { firstName lastName } }
+        pointOfContact { name { firstName lastName } emails { primaryEmail } }
+      }
+    }
+    totalCount
+  }
+}
+```
+
+#### Create a Person
+
+```graphql
+mutation {
+  createPerson(data: {
+    name: { firstName: "Jane", lastName: "Doe" }
+    emails: { primaryEmail: "jane@example.com" }
+    position: "Head of Growth"
+    linkedInLink: { url: "https://linkedin.com/in/janedoe", label: "LinkedIn" }
+    companyId: "<company-uuid>"
+  }) {
+    id
+    name { firstName lastName }
+    createdAt
+  }
+}
+```
+
+#### Update an Opportunity stage
+
+```graphql
+mutation {
+  updateOpportunity(
+    id: "<opportunity-uuid>"
+    data: { stage: "CLOSED_WON" }
+  ) {
+    id
+    stage
+    updatedAt
+  }
+}
+```
+
+#### Create a Note linked to a Person
+
+```graphql
+mutation {
+  createNote(data: {
+    body: "Spoke on 2026-04-15 — interested in Growthub platform for their outbound motion."
+    noteTargets: {
+      createMany: {
+        data: [{ personId: "<person-uuid>" }]
+        skipDuplicates: true
+      }
+    }
+  }) {
+    id
+    body
+    createdAt
+  }
+}
+```
+
+---
+
+## REST API
+
+### Endpoint
+
+```
+GET/POST/PATCH/DELETE <TWENTY_API_URL>/api/objects/<object-name>
+```
+
+Object name is the plural lowercase form (e.g. `people`, `companies`, `opportunities`).
+
+### Examples
+
+#### List companies
+
+```bash
+curl -X GET "<TWENTY_API_URL>/api/objects/companies" \
+  -H "Authorization: Bearer $TWENTY_API_TOKEN"
+```
+
+#### Create a company via REST
+
+```bash
+curl -X POST "<TWENTY_API_URL>/api/objects/companies" \
+  -H "Authorization: Bearer $TWENTY_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Acme Corp", "domainName": {"primaryLinkUrl": "acme.com"}}'
+```
+
+#### Update an opportunity
+
+```bash
+curl -X PATCH "<TWENTY_API_URL>/api/objects/opportunities/<id>" \
+  -H "Authorization: Bearer $TWENTY_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"stage": "PROPOSAL"}'
+```
+
+---
+
+## WEBHOOKS
+
+### Outbound webhooks (Twenty → external)
+
+Twenty can fire outbound webhooks on object lifecycle events. Configure in:  
+**Settings > API > Webhooks > Add Webhook**
+
+Or create via the workflow engine using the `SEND_HTTP_REQUEST` action type.
+
+**Event naming convention:** `<object>.<event>` (e.g. `opportunity.created`, `person.updated`)
+
+**Outbound webhook payload schema:**
+
+```json
+{
+  "targetUrl": "https://your-endpoint.com/webhook",
+  "eventName": "opportunity.created",
+  "workspaceId": "<workspace-uuid>",
+  "webhookId": "<webhook-uuid>",
+  "eventDate": "2026-04-15T10:00:00.000Z",
+  "objectMetadata": {
+    "id": "<object-uuid>",
+    "nameSingular": "opportunity"
+  },
+  "record": {
+    "id": "<record-uuid>",
+    "name": "Acme Corp — Deal",
+    "stage": "LEAD",
+    "createdAt": "2026-04-15T10:00:00.000Z"
+  }
+}
+```
+
+**Note:** The exact `record` payload structure depends on the object and Twenty version. Inspect the actual webhook in the Twenty UI or via a test event before finalizing payload parsing.
+
+### Inbound webhooks (external → Twenty)
+
+Twenty does not natively receive inbound webhooks — you must build a webhook receiver that:
+1. validates the incoming event signature (from the source system)
+2. transforms the payload to the Twenty GraphQL mutation format
+3. calls the Twenty API to create or update the relevant record
+
+See `docs/twenty-fork-integration.md` for the workflow engine's inbound webhook trigger, which can be used to trigger automations from external systems.
+
+### Retry policy
+
+Twenty's outbound webhooks retry on failure with exponential backoff. The default retry count and backoff schedule depend on the Twenty version. Check the workflow logs in Settings > Workflows for retry status.
+
+---
+
+## METADATA API
+
+Used to create and manage custom objects and fields programmatically.
+
+### Endpoint
+
+```
+POST <TWENTY_API_URL>/metadata
+Authorization: Bearer <TWENTY_API_TOKEN>
+```
+
+### Introspect existing metadata
+
+```graphql
+query {
+  objects {
+    edges {
+      node {
+        id
+        nameSingular
+        labelSingular
+        isActive
+        fields {
+          edges {
+            node {
+              id
+              name
+              type
+              isNullable
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## ERROR HANDLING
+
+| HTTP Status | Meaning | Action |
+|---|---|---|
+| 200 | Success | Check `errors` array in GraphQL response body |
+| 401 | Unauthorized | Token is missing, expired, or wrong workspace |
+| 403 | Forbidden | Token valid but lacks access to the resource |
+| 404 | Not found | Object ID does not exist |
+| 429 | Rate limited | Back off and retry after the period indicated in headers |
+| 500 | Server error | Log and retry; contact workspace admin if persistent |
+
+**GraphQL errors** are returned with HTTP 200 but include an `errors` array. Always check `body.errors` after parsing the response.

package/assets/worker-kits/growthub-twenty-crm-v1/docs/data-model-layer.md

@@ -0,0 +1,172 @@
+# Data Model Layer — Twenty CRM
+
+**Kit:** `growthub-twenty-crm-v1`
+
+---
+
+## OVERVIEW
+
+Twenty CRM's data model layer controls how objects, fields, and relations are defined, stored, and exposed via the API. Understanding this layer is essential for designing accurate CRM schemas and writing reliable migration or enrichment scripts.
+
+---
+
+## STANDARD VS. CUSTOM OBJECTS
+
+### Standard objects
+
+Standard objects ship with Twenty and cannot be deleted. Their core fields are fixed, but additional custom fields can be added.
+
+| Object | Purpose | Key standard fields |
+|---|---|---|
+| `Person` | Individual contact | `name`, `emails`, `phones`, `company` (relation), `position`, `linkedInLink`, `city` |
+| `Company` | Organization | `name`, `domainName`, `employees`, `annualRecurringRevenue`, `address`, `linkedInLink` |
+| `Opportunity` | Sales pipeline item | `name`, `stage`, `amount`, `closeDate`, `pointOfContact` (relation), `company` (relation) |
+| `Note` | Freeform text | `body`, `noteTargets` (polymorphic relation to any object) |
+| `Task` | Action item | `title`, `body`, `dueAt`, `assignee` (relation to WorkspaceMember), `taskTargets` |
+| `Workspace Member` | CRM user | `name`, `email`, `role` |
+
+### Custom objects
+
+Custom objects are created via:
+- **UI:** Settings > Objects > `+ New custom object`
+- **Metadata API:** `createOneObject` mutation at `/metadata`
+
+Once created and activated, custom objects are immediately queryable and mutable via the GraphQL API using automatically generated resolvers.
+
+**Custom object naming:**
+- `nameSingular`: camelCase (e.g. `partnerAccount`)
+- `namePlural`: camelCase plural (e.g. `partnerAccounts`)
+- `labelSingular`: Display name singular (e.g. `Partner Account`)
+- `labelPlural`: Display name plural (e.g. `Partner Accounts`)
+
+---
+
+## FIELD TYPES
+
+| Type | Description | Example values |
+|---|---|---|
+| `TEXT` | Single-line string | `"Jane Doe"`, `"San Francisco"` |
+| `RICH_TEXT` | Multi-line rich text | Note body, description |
+| `NUMBER` | Integer or decimal | `250`, `4.5` |
+| `BOOLEAN` | True/false | `true`, `false` |
+| `DATE` | Date only (ISO 8601) | `"2026-04-15"` |
+| `DATE_TIME` | Date and time (ISO 8601) | `"2026-04-15T10:00:00.000Z"` |
+| `SELECT` | Single choice from options | `"QUALIFIED"`, `"CLOSED_WON"` |
+| `MULTI_SELECT` | Multiple choices | `["INBOUND", "REFERRAL"]` |
+| `RELATION` | Link to another object | `{ id: "<uuid>" }` |
+| `LINK` | URL with optional label | `{ url: "https://...", label: "LinkedIn" }` |
+| `EMAILS` | Multi-email with primary | `{ primaryEmail: "jane@example.com" }` |
+| `PHONES` | Multi-phone with primary | `{ primaryPhoneNumber: "+14155550100" }` |
+| `CURRENCY` | Amount + currency code | `{ amountMicros: 10000000, currencyCode: "USD" }` |
+| `ADDRESS` | Structured address | `{ addressStreet1: "...", addressCity: "...", addressCountryCode: "US" }` |
+| `RATING` | Star rating (1–5) | `"RATING_4"` |
+| `FULL_NAME` | First + last name pair | `{ firstName: "Jane", lastName: "Doe" }` |
+| `UUID` | Universally unique identifier | `"a3d9f2..."` |
+
+---
+
+## RELATIONS
+
+Twenty uses three types of relations between objects:
+
+| Relation type | Description |
+|---|---|
+| One-to-one | One record on each side (rare) |
+| One-to-many | One parent record links to many child records (e.g. Company → many Persons) |
+| Many-to-many | Records on both sides can link to multiple records on the other side |
+
+### Relation field definition
+
+When you add a RELATION field to an object, you define:
+- **Source object** (where the field appears)
+- **Target object** (what it links to)
+- **Cardinality** (one-to-one, one-to-many, many-to-many)
+- **Field name** on both the source and target sides
+
+### Standard relation examples
+
+```text
+Person ─── company (manyToOne) ──> Company
+Company ─── people (oneToMany) ──> [Person]
+
+Opportunity ─── pointOfContact (manyToOne) ──> Person
+Opportunity ─── company (manyToOne) ──> Company
+
+Note ─── noteTargets (polymorphic) ──> [Person | Company | Opportunity | ...]
+Task ─── taskTargets (polymorphic) ──> [Person | Company | Opportunity | ...]
+```
+
+---
+
+## SELECT FIELD OPTIONS
+
+SELECT fields require predefined options. Each option has:
+- `value`: internal identifier, `SCREAMING_SNAKE_CASE` (e.g. `CLOSED_WON`)
+- `label`: display name (e.g. `Closed Won`)
+- `color`: optional UI color for the badge
+- `position`: display order
+
+**Opportunity stage options (default):**
+
+| Value | Label | Typical position |
+|---|---|---|
+| `LEAD` | Lead | 1 |
+| `QUALIFIED` | Qualified | 2 |
+| `MEETING` | Meeting | 3 |
+| `PROPOSAL` | Proposal | 4 |
+| `CUSTOMER` | Customer | 5 |
+| `CLOSED` | Closed | 6 |
+
+**Note:** The exact default stage values depend on the Twenty version and workspace seed. Inspect the actual Opportunity object in your workspace before mapping stage values in automation or import scripts.
+
+---
+
+## CURRENCY FIELD: MICROS FORMAT
+
+Twenty stores currency amounts in **micros** (millionths of the base unit) to avoid floating-point precision issues.
+
+**Conversion:**
+- `$10,000` → `amountMicros: 10000000000` (multiply by 1,000,000)
+- `amountMicros: 5000000` → `$5` (divide by 1,000,000)
+
+Always convert amounts to micros before writing to the API. Always divide by 1,000,000 when reading amounts for display.
+
+---
+
+## ID FORMAT
+
+All Twenty record IDs are UUIDs (version 4). Example:
+
+```
+a3d9f2c1-4b5e-4a8b-9c7d-0e1f2a3b4c5d
+```
+
+Never assume sequential IDs. Use the UUID when referencing related records in mutations.
+
+---
+
+## SYSTEM FIELDS
+
+Every object (standard or custom) automatically includes these system fields:
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | UUID | Primary key — auto-generated |
+| `createdAt` | DATE_TIME | Set at creation — do not override |
+| `updatedAt` | DATE_TIME | Set on every update — do not override |
+| `deletedAt` | DATE_TIME | Set on soft delete — null if record is active |
+
+Do not create custom fields with these names.
+
+---
+
+## DATABASE LAYER
+
+Twenty uses PostgreSQL. Each workspace has its own schema (multi-tenant by schema). Custom objects create new tables within the workspace schema.
+
+For local-fork development:
+- PostgreSQL runs on `localhost:5432` (Docker)
+- Default credentials are in `.env` (from `.env.example`)
+- Use `npx nx run twenty-server:database:migrate` to run migrations after code changes
+
+**Do not query the database directly in production.** Always use the GraphQL or REST API. Direct database access is only appropriate during local-fork development for schema inspection.