@knocklabs/agent-toolkit 0.1.14 → 0.2.0

package/README.md

@@ -12,6 +12,7 @@
   - [AI SDK](#ai-sdk)
   - [OpenAI](#openai)
   - [Langchain](#langchain)
+  - [Mastra](#mastra)
 
 ## Getting started
 
@@ -227,3 +228,44 @@ export async function POST(req: Request) {
   return LangChainAdapter.toDataStreamResponse(stream);
 }
 ```
+
+### Mastra
+
+The agent toolkit provides a `createKnockToolkit` under the `/mastra` path for easily integrating into the Mastra framework and returning tools ready for use.
+
+1. Install the package:
+
+```
+npm install @knocklabs/agent-toolkit
+```
+
+2. Import the `createKnockToolkit` helper, configure it, and use it in your LLM calling:
+
+```typescript
+import { anthropic } from "@ai-sdk/anthropic";
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+import { createKnockToolkit } from "@knocklabs/agent-toolkit/mastra";
+
+const toolkit = await createKnockToolkit({
+  serviceToken: "knock_st_",
+  permissions: {
+    // (optional but recommended): Set the permissions of the tools to expose
+    workflows: { read: true, run: true, manage: true },
+  },
+  userId: "10",
+});
+
+export const weatherAgent = new Agent({
+  name: "Weather Agent",
+  instructions: `You are a helpful weather assistant that provides accurate weather information.`,
+  model: anthropic("claude-3-5-sonnet-20241022"),
+  tools: toolkit.getAllTools(),
+  memory: new Memory({
+    storage: new LibSQLStore({
+      url: "file:../mastra.db", // path is relative to the .mastra/output directory
+    }),
+  }),
+});
+```

package/dist/ai-sdk/index.js

@@ -9,7 +9,7 @@ import {
 import {
   getToolMap,
   getToolsByPermissionsInCategories
-} from "../chunk-RMUYOYLN.js";
+} from "../chunk-QG5UJT76.js";
 import "../chunk-G3PMV62Z.js";
 
 // src/ai-sdk/tool-converter.ts

package/dist/{chunk-RMUYOYLN.js → chunk-QG5UJT76.js}

@@ -156,7 +156,9 @@ import { z as z4 } from "zod";
 function serializeEmailLayoutResponse(emailLayout) {
   return {
     key: emailLayout.key,
-    name: emailLayout.name
+    name: emailLayout.name,
+    htmlContent: emailLayout.html_layout,
+    textContent: emailLayout.text_layout
   };
 }
 var listEmailLayouts = KnockTool({
@@ -180,11 +182,45 @@ var listEmailLayouts = KnockTool({
     return allEmailLayouts;
   }
 });
+var createOrUpdateEmailLayout = KnockTool({
+  method: "upsert_email_layout",
+  name: "Create or update email layout",
+  description: `Create or update a new email layout within the environment given. Use this tool when you need to define shared pieces of content across multiple email templates, like a header/footer. The email layout will be used to render the email template.
+
+  Here are the rules for creating an email layout:
+
+  - Every email layout must have a \`{{ content }}\` tag. This is where the content of the email will be injected.
+  - You must set both an HTML and text version of the email layout.
+  - CSS should be included in the HTML version of the email layout under <style> tags.
+  `,
+  parameters: z4.object({
+    environment: z4.string().optional().describe(
+      "(string): The environment to create or update the email layout for. Defaults to `development`."
+    ),
+    key: z4.string().describe("(string): The key of the email layout to create or update."),
+    name: z4.string().describe("(string): The name of the email layout."),
+    htmlContent: z4.string().describe("(string): The HTML content of the email layout."),
+    textContent: z4.string().describe("(string): The text content of the email layout.")
+  }),
+  execute: (knockClient, config) => async (params) => {
+    const response = await knockClient.emailLayouts.upsert(params.key, {
+      environment: params.environment ?? config.environment ?? "development",
+      email_layout: {
+        name: params.name,
+        html_layout: params.htmlContent,
+        text_layout: params.textContent
+      }
+    });
+    return serializeEmailLayoutResponse(response.email_layout);
+  }
+});
 var emailLayouts = {
-  listEmailLayouts
+  listEmailLayouts,
+  createOrUpdateEmailLayout
 };
 var permissions4 = {
-  read: ["listEmailLayouts"]
+  read: ["listEmailLayouts"],
+  manage: ["createOrUpdateEmailLayout"]
 };
 
 // src/lib/tools/environments.ts
@@ -245,7 +281,7 @@ var listMessageTypes = KnockTool({
   }
 });
 var createOrUpdateMessageType = KnockTool({
-  method: "create_or_update_message_type",
+  method: "upsert_message_type",
   name: "Create or update message type",
   description: `
   Create or update a message type. A message type is a schema that defines fields available to an editor within Knock. Message types always have at least one variant, that MUST be named "default". Use this tool when you need to create a new message type, or update an existing message type.
@@ -401,7 +437,7 @@ var getObject = KnockTool({
   }
 });
 var createOrUpdateObject = KnockTool({
-  method: "create_or_update_object",
+  method: "upsert_object",
   name: "Create or update object",
   description: `Create or update an object in a specific collection. Objects are used to model custom collections in Knock that are NOT users or tenants. If the object does not exist, it will be created. If the object exists, it will be updated with the provided properties. The update will always perform an upsert operation, so you do not need to provide the full properties each time.
   
@@ -640,9 +676,9 @@ var listTenants = KnockTool({
     return await publicClient.tenants.list();
   }
 });
-var setTenant = KnockTool({
-  method: "set_tenant",
-  name: "Set tenant",
+var createOrUpdateTenant = KnockTool({
+  method: "upsert_tenant",
+  name: "Create or update tenant",
   description: `
   Creates or updates a tenant using the properties provided. Tenants in Knock are used to model organizations, teams, and other groups of users. They are a special type of object.
   
@@ -667,11 +703,11 @@ var setTenant = KnockTool({
 var tenants = {
   getTenant,
   listTenants,
-  setTenant
+  createOrUpdateTenant
 };
 var permissions10 = {
   read: ["getTenant", "listTenants"],
-  manage: ["setTenant"]
+  manage: ["createOrUpdateTenant"]
 };
 
 // src/lib/tools/users.ts
@@ -851,7 +887,7 @@ var getUser = KnockTool({
   }
 });
 var createOrUpdateUser = KnockTool({
-  method: "create_or_update_user",
+  method: "upsert_user",
   name: "Create or update user",
   description: `
   Creates a new user if they don't exist, or updates the user object for the given userId, including email, name, phone number, and any custom properties.
@@ -1044,11 +1080,18 @@ function generateStepRef(stepType) {
   return `${stepType}_${randomString}`;
 }
 async function updateWorkflowWithStep(knockClient, workflow2, step, environment) {
+  let workflowSteps = workflow2.steps;
+  const existingStepIdx = workflow2.steps.findIndex((s) => s.ref === step.ref);
+  if (existingStepIdx !== -1) {
+    workflowSteps[existingStepIdx] = step;
+  } else {
+    workflowSteps.push(step);
+  }
   const workflowParams = {
     environment,
     workflow: {
       ...workflow2,
-      steps: [...workflow2.steps, step]
+      steps: workflowSteps
     }
   };
   const result = await knockClient.workflows.upsert(
@@ -1059,7 +1102,9 @@ async function updateWorkflowWithStep(knockClient, workflow2, step, environment)
 }
 var SHARED_PROMPTS = {
   workflow: `
-  To use this tool, you MUST first create a workflow using the \`createWorkflow\` tool, or get an existing workflow using the \`getWorkflow\` tool. You ONLY need to pass the workflow key to this tool and the sms step will be added to the end of the workflow's steps array.
+  To use this tool, you MUST first create a workflow using the \`createWorkflow\` tool, or get an existing workflow using the \`getWorkflow\` tool. 
+  
+  If you are updating an existing step, you can pass the \`stepRef\` parameter to the tool. If you do not pass the \`stepRef\` parameter, a new step will be created and added to the end of the workflow's steps array. You should ONLY pass the \`stepRef\` parameter if you are updating an existing step.
   `,
   liquid: `
   ## Personalization
@@ -1067,7 +1112,7 @@ var SHARED_PROMPTS = {
   If you need to include personalization, you can use liquid to include dynamic content in the email and the subject line.
   The following variables are always available to use in liquid:
 
-  - \`recipient.id\`: The ID of the recipient.  
+  - \`recipient.id\`: The ID of the recipient.
   - \`recipient.name\`: The name of the recipient.
   - \`recipient.email\`: The email of the recipient.
   - \`recipient.phone_number\`: The phone number of the recipient.
@@ -1077,8 +1122,8 @@ var SHARED_PROMPTS = {
   <example>
   # Hello, {{ recipient.name }}
 
-  This is a dynamic message: 
-  
+  This is a dynamic message:
+
   > {{ data.message }}
   </example>
 
@@ -1091,17 +1136,56 @@ var SHARED_PROMPTS = {
   </example>
   `
 };
-var createEmailStepInWorkflow = KnockTool({
-  method: "create_email_step_in_workflow",
-  name: "Create email step in workflow",
+var contentBlockSchema = z13.union([
+  z13.object({
+    type: z13.literal("markdown"),
+    content: z13.string().describe("(string): The markdown content of the block.")
+  }),
+  z13.object({
+    type: z13.literal("html"),
+    content: z13.string().describe("(string): The HTML content of the block.")
+  }),
+  z13.object({
+    type: z13.literal("image"),
+    url: z13.string().describe("(string): The URL of the image.")
+  }),
+  z13.object({
+    type: z13.literal("button_set"),
+    buttons: z13.array(
+      z13.object({
+        label: z13.string().describe("(string): The label of the button."),
+        action: z13.string().describe("(string): The action of the button."),
+        variant: z13.enum(["solid", "outline"]).default("solid").describe(
+          "(enum): The variant of the button. Defaults to `solid`."
+        )
+      })
+    ).describe("(array): The buttons for the button set.")
+  }),
+  z13.object({
+    type: z13.literal("divider")
+  }),
+  z13.object({
+    type: z13.literal("partial"),
+    key: z13.string().describe("(string): The key of the partial to use."),
+    name: z13.string().describe("(string): The name of the partial."),
+    attrs: z13.record(z13.string(), z13.string()).describe(
+      "(object): The attributes for the partial. ALWAYS supply an empty object when you don't know which params are required."
+    )
+  })
+]);
+var createOrUpdateEmailStepInWorkflow = KnockTool({
+  method: "upsert_workflow_email_step",
+  name: "Create or update email step in workflow",
   description: `
-  Creates an email step in a workflow. Use this tool when you're asked to create an email notification and you need to specify the content of the email.
+  Creates or updates an email step in a workflow. Use this tool when you're asked to create an email notification and you need to specify the content of the email.
 
   ${SHARED_PROMPTS.workflow}
 
+  When you're asked to create an email step, you can either set the HTML content directly or use blocks to build the email. If you're asked to set the HTML content directly, you can use the \`htmlContent\` parameter. We prefer to use blocks.
+
   ## Blocks
 
-  The content of the email is supplied as an array of "blocks". The simplest block is a "markdown" block, which supports content in a markdown format. That should always be your default block type. 
+  The content of the email is supplied as an array of "blocks". The simplest block is a "markdown" block, which supports content in a markdown format. That should always be your default block type.
 
   The following block types are supported:
 
@@ -1148,7 +1232,7 @@ Hello, {{ recipient.name }}."
   }
   </example>
 
-  ### HTML 
+  ### HTML
 
   The \`html\` block supports raw HTML content. This should be used sparingly, and only when you need to include custom HTML content that markdown doesn't support. When using the \`html\` block, you must supply a \`content\` key. HTML content can include liquid personalization.
 
@@ -1196,7 +1280,16 @@ Hello, {{ recipient.name }}."
   `,
   parameters: z13.object({
     workflowKey: z13.string().describe("(string): The key of the workflow to add the step to."),
-    blocks: z13.array(z13.any()).describe("(array): The blocks for the email step."),
+    stepRef: z13.string().optional().describe(
+      "(string): The reference of the step to update. If not provided, a new step will be created."
+    ),
+    htmlContent: z13.string().describe(
+      "(string): The HTML content of the email template. Use this when not setting blocks."
+    ),
+    blocks: z13.array(contentBlockSchema).describe(
+      "(array): The blocks for the email step. Use this when you don't need to set HTML directly."
+    ),
+    layoutKey: z13.string().describe("(string): The key of the layout to use for the email step."),
     subject: z13.string().describe("(string): The subject of the email step.")
   }),
   execute: (knockClient, config) => async (params) => {
@@ -1219,29 +1312,33 @@ Hello, {{ recipient.name }}."
         channel_key: emailChannels[0].key,
         template: {
           settings: {
-            layout_key: "default"
+            layout_key: params.layoutKey ?? "default"
           },
           subject: params.subject,
-          visual_blocks: params.blocks
+          visual_blocks: params.blocks,
+          html_content: params.htmlContent
         },
-        ref: generateStepRef("email")
+        ref: params.stepRef ?? generateStepRef("email")
       },
       config.environment ?? "development"
     );
   }
 });
-var createSmsStepInWorkflow = KnockTool({
-  method: "create_sms_step_in_workflow",
-  name: "Create sms step in workflow",
+var createOrUpdateSmsStepInWorkflow = KnockTool({
+  method: "upsert_workflow_sms_step",
+  name: "Create or update sms step in workflow",
   description: `
-  Creates an SMS step in a workflow. Use this tool when you're asked to create an SMS notification and you need to specify the content of the SMS. 
-  
+  Creates an SMS step in a workflow. Use this tool when you're asked to create an SMS notification and you need to specify the content of the SMS.
+
   ${SHARED_PROMPTS.workflow}
 
   ${SHARED_PROMPTS.liquid}
   `,
   parameters: z13.object({
     workflowKey: z13.string().describe("(string): The key of the workflow to add the step to."),
+    stepRef: z13.string().optional().describe(
+      "(string): The reference of the step to update. If not provided, a new step will be created."
+    ),
     content: z13.string().describe("(string): The content of the SMS.")
   }),
   execute: (knockClient, config) => async (params) => {
@@ -1265,15 +1362,15 @@ var createSmsStepInWorkflow = KnockTool({
         template: {
           text_body: params.content
         },
-        ref: generateStepRef("sms")
+        ref: params.stepRef ?? generateStepRef("sms")
       },
       config.environment ?? "development"
     );
   }
 });
-var createPushStepInWorkflow = KnockTool({
-  method: "create_push_step_in_workflow",
-  name: "Create push step in workflow",
+var createOrUpdatePushStepInWorkflow = KnockTool({
+  method: "upsert_workflow_push_step",
+  name: "Create or update push step in workflow",
   description: `
   Creates a push step in a workflow. Use this tool when you're asked to create a push notification and you need to specify the content of the push notification.
 
@@ -1285,6 +1382,9 @@ var createPushStepInWorkflow = KnockTool({
   `,
   parameters: z13.object({
     workflowKey: z13.string().describe("(string): The key of the workflow to add the step to."),
+    stepRef: z13.string().optional().describe(
+      "(string): The reference of the step to update. If not provided, a new step will be created."
+    ),
     title: z13.string().describe("(string): The title of the push notification."),
     content: z13.string().describe("(string): The content (body) of the push notification.")
   }),
@@ -1310,17 +1410,17 @@ var createPushStepInWorkflow = KnockTool({
           title: params.title,
           text_body: params.content
         },
-        ref: generateStepRef("push")
+        ref: params.stepRef ?? generateStepRef("push")
       },
       config.environment ?? "development"
     );
   }
 });
-var createInAppFeedStepInWorkflow = KnockTool({
-  method: "create_in_app_feed_step_in_workflow",
-  name: "Create in app feed step in workflow",
+var createOrUpdateInAppFeedStepInWorkflow = KnockTool({
+  method: "upsert_workflow_in_app_step",
+  name: "Create or update in app feed step in workflow",
   description: `
-  Creates an in app feed step in a workflow. Use this tool when you're asked to create an in app feed notification and you need to specify the content of the in app feed notification.  
+  Creates an in app feed step in a workflow. Use this tool when you're asked to create an in app feed notification and you need to specify the content of the in app feed notification.
 
   ${SHARED_PROMPTS.workflow}
 
@@ -1328,6 +1428,9 @@ var createInAppFeedStepInWorkflow = KnockTool({
   `,
   parameters: z13.object({
     workflowKey: z13.string().describe("(string): The key of the workflow to add the step to."),
+    stepRef: z13.string().optional().describe(
+      "(string): The reference of the step to update. If not provided, a new step will be created."
+    ),
     actionUrl: z13.string().describe(
       "(string): The URL to navigate to when the in app feed is tapped."
     ),
@@ -1355,15 +1458,15 @@ var createInAppFeedStepInWorkflow = KnockTool({
           action_url: params.actionUrl,
           markdown_body: params.body
         },
-        ref: generateStepRef("in_app_feed")
+        ref: params.stepRef ?? generateStepRef("in_app_feed")
       },
       config.environment ?? "development"
     );
   }
 });
-var createChatStepInWorkflow = KnockTool({
-  method: "create_chat_step_in_workflow",
-  name: "Create chat step in workflow",
+var createOrUpdateChatStepInWorkflow = KnockTool({
+  method: "upsert_workflow_chat_step",
+  name: "Create or update chat step in workflow",
   description: `
   Creates a chat step in a workflow. Use this tool when you're asked to create a chat, Slack, Discord, or Microsoft Teams notification and you need to specify the content of the chat notification.
 
@@ -1373,6 +1476,9 @@ var createChatStepInWorkflow = KnockTool({
   `,
   parameters: z13.object({
     workflowKey: z13.string().describe("(string): The key of the workflow to add the step to."),
+    stepRef: z13.string().describe(
+      "(string): The reference of the step to update. If not provided, a new step will be created."
+    ),
     body: z13.string().describe("(string): The markdown content of the notification.")
   }),
   execute: (knockClient, config) => async (params) => {
@@ -1396,20 +1502,20 @@ var createChatStepInWorkflow = KnockTool({
         template: {
           markdown_body: params.body
         },
-        ref: generateStepRef("chat")
+        ref: params.stepRef ?? generateStepRef("chat")
       },
       config.environment ?? "development"
     );
   }
 });
-var createDelayStepInWorkflow = KnockTool({
-  method: "create_delay_step_in_workflow",
-  name: "Create delay step in workflow",
+var createOrUpdateDelayStepInWorkflow = KnockTool({
+  method: "upsert_workflow_delay_step",
+  name: "Create or update delay step in workflow",
   description: `
   Creates a delay step in a workflow. Use this tool when you're asked to add a delay to the workflow that pauses, or waits for a period of time before continuing.
 
   ${SHARED_PROMPTS.workflow}
-  
+
   Delays are specified in "unit" and "value" pairs. The only valid units are "seconds", "minutes", "hours", and "days".
 
   <example>
@@ -1421,6 +1527,9 @@ var createDelayStepInWorkflow = KnockTool({
   `,
   parameters: z13.object({
     workflowKey: z13.string().describe("(string): The key of the workflow to add the step to."),
+    stepRef: z13.string().optional().describe(
+      "(string): The reference of the step to update. If not provided, a new step will be created."
+    ),
     delayValue: z13.number().describe("(number): The value of the delay."),
     delayUnit: z13.enum(["seconds", "minutes", "hours", "days"]).describe("(enum): The unit of the delay.")
   }),
@@ -1444,7 +1553,7 @@ var createDelayStepInWorkflow = KnockTool({
                 unit: params.delayUnit
               }
             },
-            ref: generateStepRef("delay")
+            ref: params.stepRef ?? generateStepRef("delay")
           }
         ]
       }
@@ -1456,9 +1565,9 @@ var createDelayStepInWorkflow = KnockTool({
     return serializeWorkflowResponse(result.workflow);
   }
 });
-var createBatchStepInWorkflow = KnockTool({
-  method: "create_batch_step_in_workflow",
-  name: "Create batch step in workflow",
+var createOrUpdateBatchStepInWorkflow = KnockTool({
+  method: "upsert_workflow_batch_step",
+  name: "Create or update batch step in workflow",
   description: `
   Creates a batch step in a workflow. Use this tool when you're asked to create a batch step or asked to add digesting behavior to a workflow. The batch step collects multiple workflow triggers for a single recipient over a period of time and then flushes the content to the next step.
 
@@ -1477,6 +1586,9 @@ var createBatchStepInWorkflow = KnockTool({
   `,
   parameters: z13.object({
     workflowKey: z13.string().describe("(string): The key of the workflow to add the step to."),
+    stepRef: z13.string().optional().describe(
+      "(string): The reference of the step to update. If not provided, a new step will be created."
+    ),
     batchWindow: z13.object({
       value: z13.number().describe("(number): The value of the batch window."),
       unit: z13.enum(["seconds", "minutes", "hours", "days"]).describe("(enum): The unit of the batch window.")
@@ -1498,7 +1610,7 @@ var createBatchStepInWorkflow = KnockTool({
             unit: params.batchWindow.unit
           }
         },
-        ref: generateStepRef("batch")
+        ref: params.stepRef ?? generateStepRef("batch")
       },
       config.environment ?? "development"
     );
@@ -1506,14 +1618,14 @@ var createBatchStepInWorkflow = KnockTool({
 });
 var workflowStepTools = {
   // Channel steps
-  createEmailStepInWorkflow,
-  createSmsStepInWorkflow,
-  createPushStepInWorkflow,
-  createInAppFeedStepInWorkflow,
-  createChatStepInWorkflow,
+  createOrUpdateEmailStepInWorkflow,
+  createOrUpdateSmsStepInWorkflow,
+  createOrUpdatePushStepInWorkflow,
+  createOrUpdateInAppFeedStepInWorkflow,
+  createOrUpdateChatStepInWorkflow,
   // Function steps
-  createDelayStepInWorkflow,
-  createBatchStepInWorkflow
+  createOrUpdateDelayStepInWorkflow,
+  createOrUpdateBatchStepInWorkflow
 };
 
 // src/lib/tools/workflows.ts
@@ -1526,6 +1638,16 @@ function serializeWorkflowResponse(workflow2) {
     schema: workflow2.trigger_data_json_schema
   };
 }
+function serializeFullWorkflowResponse(workflow2) {
+  return {
+    key: workflow2.key,
+    name: workflow2.name,
+    description: workflow2.description,
+    categories: workflow2.categories,
+    schema: workflow2.trigger_data_json_schema,
+    steps: workflow2.steps
+  };
+}
 var listWorkflows = KnockTool({
   method: "list_workflows",
   name: "List workflows",
@@ -1566,7 +1688,7 @@ var getWorkflow = KnockTool({
     const workflow2 = await knockClient.workflows.retrieve(params.workflowKey, {
       environment: params.environment ?? config.environment ?? "development"
     });
-    return serializeWorkflowResponse(workflow2);
+    return serializeFullWorkflowResponse(workflow2);
   }
 });
 var triggerWorkflow = KnockTool({
@@ -1740,4 +1862,4 @@ export {
   getToolsByPermissionsInCategories,
   getToolMap
 };
-//# sourceMappingURL=chunk-RMUYOYLN.js.map
+//# sourceMappingURL=chunk-QG5UJT76.js.map