@kelpi/mcp 0.1.0

package/dist/tools/flows/index.js

@@ -0,0 +1,183 @@
+import { createFlowInputSchema, listFlowsInputSchema, activateFlowInputSchema, } from './schemas.js';
+import { createFlowHandler } from './create.js';
+import { listFlowsHandler } from './list.js';
+import { activateFlowHandler } from './activate.js';
+/**
+ * kelpi_create_flow tool definition and handler
+ *
+ * Creates a new automation flow from a JSON definition.
+ */
+export const kelpiCreateFlow = {
+    definition: {
+        name: 'kelpi_create_flow',
+        description: `Create a new engagement flow with triggers, actions, and conditions.
+
+This tool creates an automation flow that can:
+- Trigger on events (e.g., "user.signed_up", "trial.started")
+- Trigger based on segment membership
+
+The flow definition should include:
+- name: A descriptive name for the flow (required)
+- trigger_type: "event" or "segment" (required)
+- trigger_event: Required when trigger_type is "event"
+- trigger_segment_id: Required when trigger_type is "segment"
+- steps: Array of flow steps with required step_id and step_order
+
+Step types:
+- email: Sends an email (configure content via emails table)
+- delay: Waits for delay_seconds or delay_expression
+- webhook: Calls webhook_url with optional payload_template
+- condition: Evaluates condition_filter as a gate (see TYPED CONDITIONS below)
+
+=== ENTRY FILTER (for flow entry) ===
+Uses simple field/operator/value conditions:
+{
+  "logic": "AND" | "OR",
+  "conditions": [
+    { "field": "plan", "operator": "equals", "value": "pro" },
+    { "field": "country", "operator": "in", "value": ["US", "CA"] }
+  ]
+}
+
+Operators for entry_filter:
+- equals, not_equals (aliases: eq, neq)
+- contains, not_contains, starts_with, ends_with
+- greater_than, less_than, greater_than_or_equals, less_than_or_equals (aliases: gt, lt, gte, lte)
+- is_set, is_not_set
+- in, not_in
+
+=== TYPED CONDITIONS (for condition steps) ===
+IMPORTANT: condition_filter in condition steps uses TYPED conditions, not simple field/value!
+
+The condition_filter must have "type": "group" at the top level, and each condition
+must specify its type ("event" or "property").
+
+Event condition - check if contact performed an event:
+{
+  "type": "group",
+  "logic": "AND",
+  "conditions": [{
+    "type": "event",
+    "event_name": "subscription.created",
+    "operator": "has_done",           // or "has_not_done", "count_greater_than", "count_less_than"
+    "timeframe": { "since": "flow_start" },  // or { "days": 7 }, or "ever"
+    "properties": { "plan": "pro" }   // optional: filter by event properties
+  }]
+}
+
+Property condition - check a contact property:
+{
+  "type": "group",
+  "logic": "AND",
+  "conditions": [{
+    "type": "property",
+    "field": "cso_email",
+    "operator": "is_set"              // or any standard operator with "value"
+  }]
+}
+
+Event operators:
+- has_done, has_not_done: Check if event occurred
+- count_greater_than, count_less_than: Check event count (requires "count" field)
+
+Timeframe options:
+- { "since": "flow_start" }: Since the contact entered this flow
+- { "days": N }: Within the last N days
+- "ever": Any time in history
+
+=== FULL EXAMPLE WITH CONDITION STEPS ===
+{
+  "name": "Trial Expiration Reminder",
+  "trigger_type": "event",
+  "trigger_event": "trial.started",
+  "entry_filter": {
+    "logic": "AND",
+    "conditions": [
+      { "field": "plan", "operator": "equals", "value": "trial" }
+    ]
+  },
+  "steps": [
+    { "step_id": "welcome", "step_order": 0, "action_type": "email" },
+    { "step_id": "wait-3-days", "step_order": 1, "action_type": "delay", "delay_seconds": 259200 },
+    {
+      "step_id": "check-converted",
+      "step_order": 2,
+      "action_type": "condition",
+      "condition_filter": {
+        "type": "group",
+        "logic": "AND",
+        "conditions": [{
+          "type": "event",
+          "event_name": "subscription.created",
+          "operator": "has_done",
+          "timeframe": { "since": "flow_start" }
+        }]
+      }
+    },
+    { "step_id": "reminder", "step_order": 3, "action_type": "email" }
+  ]
+}`,
+        inputSchema: createFlowInputSchema,
+    },
+    handler: createFlowHandler,
+};
+/**
+ * kelpi_list_flows tool definition and handler
+ *
+ * Lists all flows in the workspace with optional filtering.
+ */
+export const kelpiListFlows = {
+    definition: {
+        name: 'kelpi_list_flows',
+        description: `List all flows in the workspace with optional filtering.
+
+Returns a paginated list of flows with their:
+- ID, name, and slug
+- Trigger type (event or segment)
+- Current status (draft, active, paused, archived)
+- Step count
+- Creation and update timestamps
+
+Optional filters:
+- status: "draft", "active", "paused", or "archived"
+- trigger_type: "event" or "segment"
+- limit: Max results (1-250, default 50)
+- offset: Skip N results (for pagination)
+- order_by: "created_at", "updated_at", "name", or "status"
+- order_direction: "asc" or "desc"`,
+        inputSchema: listFlowsInputSchema,
+    },
+    handler: listFlowsHandler,
+};
+/**
+ * kelpi_activate_flow tool definition and handler
+ *
+ * Activates a draft flow so it starts processing events.
+ */
+export const kelpiActivateFlow = {
+    definition: {
+        name: 'kelpi_activate_flow',
+        description: `Activate a draft flow so it starts processing events.
+
+Once activated, the flow will:
+- Listen for its configured trigger events
+- Start enrolling contacts that match entry criteria
+- Execute flow steps for enrolled contacts
+
+This operation is idempotent - activating an already-active flow returns success.
+
+Requirements:
+- Flow must exist
+- Flow should have at least one step (recommended)
+- Flow cannot be archived`,
+        inputSchema: activateFlowInputSchema,
+    },
+    handler: activateFlowHandler,
+};
+// Re-export schemas
+export * from './schemas.js';
+// Re-export handler factories for testing
+export { createCreateFlowHandler } from './create.js';
+export { createListFlowsHandler } from './list.js';
+export { createActivateFlowHandler } from './activate.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/flows/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/flows/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAoB;IAC9C,UAAU,EAAE;QACV,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0Gf;QACE,WAAW,EAAE,qBAAqB;KACnC;IACD,OAAO,EAAE,iBAAiB;CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAoB;IAC7C,UAAU,EAAE;QACV,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE;;;;;;;;;;;;;;;mCAekB;QAC/B,WAAW,EAAE,oBAAoB;KAClC;IACD,OAAO,EAAE,gBAAgB;CAC1B,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAoB;IAChD,UAAU,EAAE;QACV,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EAAE;;;;;;;;;;;;0BAYS;QACtB,WAAW,EAAE,uBAAuB;KACrC;IACD,OAAO,EAAE,mBAAmB;CAC7B,CAAC;AAEF,oBAAoB;AACpB,cAAc,cAAc,CAAC;AAE7B,0CAA0C;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC"}

package/dist/tools/flows/list.d.ts

@@ -0,0 +1,11 @@
+import type { ToolHandler } from '../../lib/tool-registry.js';
+/**
+ * Creates a list flows handler.
+ * This factory function allows for dependency injection in tests.
+ */
+export declare function createListFlowsHandler(): ToolHandler;
+/**
+ * Default list flows handler
+ */
+export declare const listFlowsHandler: ToolHandler;
+//# sourceMappingURL=list.d.ts.map

package/dist/tools/flows/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/tools/flows/list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,4BAA4B,CAAC;AAI1E;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,WAAW,CA2BpD;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,aAA2B,CAAC"}

package/dist/tools/flows/list.js

@@ -0,0 +1,34 @@
+import { withAuth, successResponse, handleApiError } from '../../lib/tool-helpers.js';
+/**
+ * Creates a list flows handler.
+ * This factory function allows for dependency injection in tests.
+ */
+export function createListFlowsHandler() {
+    return async (input) => {
+        return withAuth('listing flows', async ({ client }) => {
+            // Build query parameters
+            const queryParams = {};
+            if (input.status && typeof input.status === 'string') {
+                queryParams.status = input.status;
+            }
+            if (input.limit !== undefined && typeof input.limit === 'number') {
+                queryParams.limit = String(input.limit);
+            }
+            if (input.offset !== undefined && typeof input.offset === 'number') {
+                queryParams.offset = String(input.offset);
+            }
+            try {
+                const response = await client.get('/api/v1/flows', Object.keys(queryParams).length > 0 ? queryParams : undefined);
+                return successResponse(response.data);
+            }
+            catch (err) {
+                return handleApiError(err, 'list flows');
+            }
+        });
+    };
+}
+/**
+ * Default list flows handler
+ */
+export const listFlowsHandler = createListFlowsHandler();
+//# sourceMappingURL=list.js.map

package/dist/tools/flows/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../src/tools/flows/list.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGtF;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,KAAK,EAAE,KAA8B,EAAuB,EAAE;QACnE,OAAO,QAAQ,CAAC,eAAe,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;YACpD,yBAAyB;YACzB,MAAM,WAAW,GAA2B,EAAE,CAAC;YAE/C,IAAI,KAAK,CAAC,MAAM,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACrD,WAAW,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YACpC,CAAC;YACD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACjE,WAAW,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1C,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACnE,WAAW,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC5C,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,GAAG,CAC/B,eAAe,EACf,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAC9D,CAAC;gBACF,OAAO,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACxC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,cAAc,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,sBAAsB,EAAE,CAAC"}