feat: Add Kommo integration

integrations/kommo/definitions/actions/index.ts

@@ -0,0 +1,2 @@
+// Re-export all lead actions
+export * from './lead'

integrations/kommo/definitions/actions/lead.ts

@@ -0,0 +1,111 @@
+import { z } from '@bpinternal/zui'
+import { ActionDefinition } from '@botpress/sdk'
+
+// Lead Schema: defines what a Kommo lead looks like in Botpress
+// This is a simplified version: we only expose the fields bots need
+
+export const leadSchema = z.object({
+  id: z.number().describe('Lead ID'),
+  name: z.string().describe('Lead name'),
+  price: z.number().optional().describe('Lead value in dollars'),
+  responsibleUserId: z.number().optional().describe('User responsible for this lead'),
+  pipelineId: z.number().optional().describe('Which sales pipeline'),
+  statusId: z.number().optional().describe('Which stage in the pipeline'),
+  createdAt: z.number().describe('When created (Unix timestamp)'),
+  updatedAt: z.number().describe('When last updated (Unix timestamp)'),
+})
+
+/**
+ * Create Lead Action
+ * Creates a new lead in Kommo CRM
+ */
+const createLead: ActionDefinition = {
+  title: 'Create Lead',
+  description: 'Creates a new lead in Kommo CRM',
+  input: {
+    schema: z.object({
+      name: z.string().describe('Lead name (required)'),
+      price: z.number().optional().describe('Lead value in dollars'),
+      responsibleUserId: z.number().optional().describe('User ID to assign this lead to'),
+      pipelineId: z.number().optional().describe('Pipeline ID (defaults to main pipeline)'),
+      statusId: z.number().optional().describe('Initial status/stage ID'),
+    }),
+  },
+  output: {
+    schema: z.object({
+      lead: leadSchema,
+    }),
+  },
+}
+
+/**
+ * Get Lead Action
+ * Retrieves a lead by its ID
+ */
+const getLead: ActionDefinition = {
+  title: 'Get Lead',
+  description: 'Retrieves a lead by ID from Kommo',
+  input: {
+    schema: z.object({
+      leadId: z.number().describe('The ID of the lead to retrieve'),
+    }),
+  },
+  output: {
+    schema: z.object({
+      lead: leadSchema.optional().describe('The lead (undefined if not found)'),
+    }),
+  },
+}
+
+/**
+ * Update Lead Action
+ * Updates an existing lead's information
+ */
+const updateLead: ActionDefinition = {
+  title: 'Update Lead',
+  description: 'Updates an existing lead in Kommo',
+  input: {
+    schema: z.object({
+      leadId: z.number().describe('Lead ID to update'),
+      name: z.string().optional().describe('New name'),
+      price: z.number().optional().describe('New price'),
+      responsibleUserId: z.number().optional().describe('New responsible user'),
+      pipelineId: z.number().optional().describe('New pipeline ID'),
+      statusId: z.number().optional().describe('New status/stage ID'),
+    }),
+  },
+  output: {
+    schema: z.object({
+      lead: leadSchema,
+    }),
+  },
+}
+
+/**
+ * Move Lead Action
+ * Moves a lead to a different pipeline stage
+ */
+const moveLead: ActionDefinition = {
+  title: 'Move Lead',
+  description: 'Moves a lead to a different pipeline stage',
+  input: {
+    schema: z.object({
+      leadId: z.number().describe('Lead ID to move'),
+      statusId: z.number().describe('New status/stage ID'),
+      pipelineId: z.number().describe('Pipeline ID'),
+    }),
+  },
+  output: {
+    schema: z.object({
+      lead: leadSchema,
+    }),
+  },
+}
+
+// Export all lead actions
+export const actions = {
+  createLead,
+  getLead,
+  updateLead,
+  moveLead,
+} as const

integrations/kommo/definitions/events.ts

@@ -0,0 +1,71 @@
+import { EventDefinition } from '@botpress/sdk'
+import { z } from '@bpinternal/zui'
+
+/**
+ * Lead Created Event
+ * Triggered when a new lead is created in Kommo
+ */
+const leadCreated: EventDefinition = {
+  title: 'Lead Created',
+  description: 'Triggered when a new lead is created in Kommo',
+  schema: z.object({
+    leadId: z.number().describe('Lead ID'),
+    name: z.string().describe('Lead name'),
+    responsibleUserId: z.number().optional().describe('User responsible for this lead'),
+    pipelineId: z.number().describe('Pipeline ID'),
+    statusId: z.number().describe('Status/Stage ID'),
+    createdAt: z.number().describe('Creation timestamp'),
+  }),
+}
+
+/**
+ * Lead Status Changed Event
+ * Triggered when a lead moves to a new pipeline stage
+ */
+const leadStatusChanged: EventDefinition = {
+  title: 'Lead Status Changed',
+  description: 'Triggered when a lead moves to a new pipeline stage',
+  schema: z.object({
+    leadId: z.number().describe('Lead ID'),
+    oldStatusId: z.number().describe('Previous status/stage ID'),
+    newStatusId: z.number().describe('New status/stage ID'),
+    pipelineId: z.number().describe('Pipeline ID'),
+    changedAt: z.number().describe('When the change occurred'),
+  }),
+}
+
+/**
+ * Lead Updated Event
+ * Triggered when lead data is changed
+ */
+const leadUpdated: EventDefinition = {
+  title: 'Lead Updated',
+  description: 'Triggered when lead data is changed',
+  schema: z.object({
+    leadId: z.number().describe('Lead ID'),
+    updatedAt: z.number().describe('When the update occurred'),
+  }),
+}
+
+/**
+ * Lead Assignment Changed Event
+ * Triggered when lead is assigned to a different user
+ */
+const leadAssignmentChanged: EventDefinition = {
+  title: 'Lead Assignment Changed',
+  description: 'Triggered when lead is assigned to a different user',
+  schema: z.object({
+    leadId: z.number().describe('Lead ID'),
+    oldUserId: z.number().describe('Previous responsible user ID'),
+    newUserId: z.number().describe('New responsible user ID'),
+    changedAt: z.number().describe('When the change occurred'),
+  }),
+}
+
+// Export all events
+export const events = {
+  leadCreated,
+  leadStatusChanged,
+  leadUpdated,
+  leadAssignmentChanged,
+} as const

integrations/kommo/definitions/index.ts

@@ -0,0 +1,4 @@
+// Re-export everything from definitions
+export * from './actions'
+export * from './events'
+export * from './states'

integrations/kommo/definitions/states.ts

@@ -0,0 +1,21 @@
+import { StateDefinition } from '@botpress/sdk'
+import { z } from '@bpinternal/zui'
+
+/**
+ * OAuth Credentials State
+ * Stores OAuth tokens and configuration for accessing Kommo API
+ */
+const oauthCredentials: StateDefinition = {
+  type: 'integration',
+  schema: z.object({
+    accessToken: z.string().describe('Access token for API calls'),
+    refreshToken: z.string().describe('Refresh token to get new access tokens'),
+    expiresAt: z.number().describe('When the access token expires (Unix timestamp)'),
+    baseDomain: z.string().describe('Kommo subdomain (e.g., yourcompany.kommo.com)'),
+  }),
+}
+
+// Export all states
+export const states = {
+  oauthCredentials,
+} as const

integrations/kommo/deploy.log

@@ -0,0 +1,24 @@
+🤖 Botpress CLI v5.2.1
+
+   ╭──────────────────────────────────────────────╮
+   │                                              │
+   │   Update available 5.2.1 → 5.4.0             │
+   │                                              │
+   │   To update, run:                            │
+   │     for npm  npm i -g @botpress/cli          │
+   │     for yarn yarn global add @botpress/cli   │
+   │     for pnpm pnpm i -g @botpress/cli         │
+   │                                              │
+   ╰──────────────────────────────────────────────╯
+
+○ Generating typings for integration kommo...
+✔ Typings available at .botpress
+
+○ Bundling integration kommo...
+✔ Bundle available at .botpress
+
+Build completed in 165ms
+⚠ Integration already exists. If you decide to deploy, it will override the existing one.
+○ Deploying integration yl_integration/kommo v0.1.0...
+✔ Integration deployed
+

integrations/kommo/hub.md

@@ -0,0 +1,43 @@
+# Hello World
+
+This integration is a template with a single action.
+
+> Describe the integration's purpose.
+
+## Configuration
+
+This integration does not need a configuration.
+
+> Explain how to configure your integration and list prerequisites `ex: accounts, etc.`.
+> You might also want to add configuration details for specific use cases.
+
+## Usage
+
+To use, call the action `helloWorld`. This action will greet the user.
+
+> Explain how to use your integration.
+> You might also want to include an example if there is a specific use case.
+
+## Limitations
+
+The `helloWorld` action has a max name size limit of 2^28 - 16 characters (the max javascript string size).
+
+> List the known bugs.
+> List known limits `ex: rate-limiting, payload sizes, etc.`
+> List unsupported use cases.
+
+## Changelog
+
+- 0.1.0: Implemented `helloWorld` action.
+
+> If some versions of your integration introduce changes worth mentionning (breaking changes, bug fixes), describe them here. This will help users to know what to expect when updating the integration.
+
+### Integration publication checklist
+
+- [ ] The register handler is implemented and validates the configuration.
+- [ ] Title and descriptions for all schemas are present in `integration.definition.ts`.
+- [ ] Events store `conversationId`, `userId` and `messageId` when available.
+- [ ] Implement events & actions that are related to `channels`, `entities`, `user`, `conversations` and `messages`.
+- [ ] Events related to messages are implemented as messages.
+- [ ] When an action is required by the bot developer, a `RuntimeError` is thrown with instructions to fix the problem.
+- [ ] Bot name and bot avatar URL fields are available in the integration configuration.

integrations/kommo/integration.definition.ts

@@ -0,0 +1,26 @@
+import { z, IntegrationDefinition } from '@botpress/sdk'
+import { integrationName } from './package.json'
+import { actions, events, states } from './definitions'
+
+export default new IntegrationDefinition({
+  name: integrationName,
+  title: 'Kommo',
+  version: '0.1.0',
+  readme: 'hub.md',
+  icon: 'icon.svg',
+
+  // User provides these when configuring the integration
+  configuration: {
+    schema: z.object({
+      baseDomain: z
+        .string()
+        .describe('Your Kommo subdomain (e.g., yourcompany.kommo.com)'),
+      accessToken: z
+        .string()
+        .describe('Long-lived access token from your Kommo private integration'),
+    }),
+  },
+  actions, 
+  events,
+  states,
+})