feat: add action versioning support

js/src/sdk/base.toolset.ts

@@ -27,6 +27,8 @@ import { Triggers } from "./models/triggers";
 import { getUserDataJson } from "./utils/config";
 import { CEG } from "./utils/error";
 import { COMPOSIO_SDK_ERROR_CODES } from "./utils/errors/src/constants";
+import { getVersionsFromLockFileAsJson } from "./utils/lockFile";
+import { actionLockProcessor } from "./utils/processor/action_lock";
 import {
   fileInputProcessor,
   fileResponseProcessor,
@@ -54,6 +56,12 @@ export class ComposioToolSet {
   activeTriggers: ActiveTriggers;
 
   userActionRegistry: ActionRegistry;
+  actionVersionMap: Record<string, string>;
+
+  lockFile: {
+    path: string | null;
+    save: boolean;
+  };
 
   private internalProcessors: {
     pre: TPreProcessor[];
@@ -79,19 +87,27 @@ export class ComposioToolSet {
    * @param {string|null} config.runtime - Runtime environment
    * @param {string} config.entityId - Entity ID for operations
    * @param {Record<string, string>} config.connectedAccountIds - Map of app names to their connected account IDs
+   * @param {Object} config.lockFile - Lock file configuration
+   * @param {string} config.lockFile.path - Path to the lock file, Default: .composio.lock
+   * @param {boolean} config.lockFile.lock - Whether to lock the file
    */
   constructor({
     apiKey,
     baseUrl,
     runtime,
     entityId,
     connectedAccountIds,
+    lockFile,
   }: {
     apiKey?: string | null;
     baseUrl?: string | null;
     runtime?: string | null;
     entityId?: string;
     connectedAccountIds?: Record<string, string>;
+    lockFile?: {
+      path: string;
+      save: boolean;
+    };
   } = {}) {
     const clientApiKey: string | undefined =
       apiKey ||
@@ -113,6 +129,23 @@ export class ComposioToolSet {
     this.integrations = this.client.integrations;
     this.activeTriggers = this.client.activeTriggers;
     this.connectedAccountIds = connectedAccountIds || {};
+    this.actionVersionMap = {};
+
+    this.lockFile = lockFile || {
+      path: ".composio.lock",
+      save: false,
+    };
+
+    if (this.lockFile.save) {
+      if (!this.lockFile.path) {
+        CEG.getCustomError(COMPOSIO_SDK_ERROR_CODES.SDK.INVALID_PARAMETER, {
+          message: "Lock file path is required when save is true",
+          description: "Lock file path is required when save is true",
+        });
+      }
+      const actionLock = actionLockProcessor.bind(this, this.lockFile.path);
+      this.internalProcessors.schema.push(actionLock);
+    }
 
     this.userActionRegistry = new ActionRegistry(this.client);
 
@@ -149,13 +182,17 @@ export class ComposioToolSet {
   ): Promise<RawActionData[]> {
     const parsedFilters = ZToolSchemaFilter.parse(filters);
 
-    const apps = await this.client.actions.list({
+    const actionVersions = this.lockFile.path
+      ? getVersionsFromLockFileAsJson(this.lockFile.path)
+      : {};
+    const actions = await this.client.actions.list({
       apps: parsedFilters.apps?.join(","),
       tags: parsedFilters.tags?.join(","),
       useCase: parsedFilters.useCase,
       actions: parsedFilters.actions?.join(","),
       usecaseLimit: parsedFilters.useCaseLimit,
       filterByAvailableApps: parsedFilters.filterByAvailableApps,
+      actionVersions: actionVersions,
     });
 
     const customActions = await this.userActionRegistry.getAllActions();
@@ -171,7 +208,7 @@ export class ComposioToolSet {
       );
     });
 
-    const toolsActions = [...(apps?.items || []), ...toolsWithCustomActions];
+    const toolsActions = [...(actions?.items || []), ...toolsWithCustomActions];
 
     const allSchemaProcessor = [
       ...this.internalProcessors.schema,
@@ -182,6 +219,10 @@ export class ComposioToolSet {
 
     return toolsActions.map((tool) => {
       let schema = tool as RawActionData;
+      if (schema?.version) {
+        // store the version in the map for execution
+        this.actionVersionMap[schema?.name.toUpperCase()] = schema?.version;
+      }
       allSchemaProcessor.forEach((processor) => {
         schema = processor({
           actionName: schema?.name,
@@ -277,11 +318,13 @@ export class ComposioToolSet {
       });
     }
 
+    const version = this.actionVersionMap[action.toUpperCase()];
     const data = await this.client.getEntity(entityId).execute({
       actionName: action,
       params: params,
       text: nlaText,
       connectedAccountId: connectedAccountId,
+      version: version,
     });
 
     return this.processResponse(data, {

js/src/sdk/models/Entity.ts

@@ -79,6 +79,7 @@ export class Entity {
     params,
     text,
     connectedAccountId,
+    version,
   }: ExecuteActionParams): Promise<ActionExecuteResponse> {
     TELEMETRY_LOGGER.manualTelemetry(TELEMETRY_EVENTS.SDK_METHOD_INVOKED, {
       method: "execute",
@@ -91,6 +92,7 @@ export class Entity {
         params,
         text,
         connectedAccountId,
+        version,
       });
       const action = await this.actionsModel.get({
         actionName: actionName,
@@ -104,6 +106,7 @@ export class Entity {
       if (app.no_auth) {
         return this.actionsModel.execute({
           actionName: actionName,
+          version: version,
           requestBody: {
             input: params,
             appName: action.appKey,
@@ -126,6 +129,7 @@ export class Entity {
       }
       return this.actionsModel.execute({
         actionName: actionName,
+        version: version,
         requestBody: {
           // @ts-ignore
           connectedAccountId: connectedAccount?.id as unknown as string,

js/src/sdk/models/actions.ts

@@ -121,6 +121,7 @@ export class Actions {
           showEnabledOnly: data.showEnabledOnly,
           usecaseLimit: data.usecaseLimit || undefined,
           useCase: data.useCase as string,
+          actionVersions: data.actionVersions,
         },
         body: {
           useCase: data.useCase as string,
@@ -155,6 +156,9 @@ export class Actions {
         path: {
           actionId: parsedData.actionName,
         },
+        query: {
+          version: parsedData.version,
+        },
       });
       return res!;
     } catch (error) {

js/src/sdk/types/action.ts

@@ -20,6 +20,7 @@ export const ZGetListActionsParams = z.object({
     .boolean()
     .optional()
     .describe("Filter actions by available apps"),
+  actionVersions: z.record(z.string()).optional(),
 });
 
 export const ZParameter = z.object({
@@ -36,6 +37,7 @@ export const ZCustomAuthParams = z.object({
 
 export const ZExecuteParams = z.object({
   actionName: z.string(),
+  version: z.string().optional(),
   requestBody: z.object({
     connectedAccountId: z.string().optional(),
     input: z.record(z.unknown()).optional(),

js/src/sdk/types/entity.ts

@@ -6,6 +6,7 @@ export const ZExecuteActionParams = z.object({
   params: z.record(z.any()).optional(),
   text: z.string().optional(),
   connectedAccountId: z.string().optional(),
+  version: z.string().optional(),
 });
 
 export const ZInitiateConnectionParams = z.object({

js/src/sdk/utils/lock/load.ts

@@ -0,0 +1,14 @@
+import fs from "fs";
+
+export const loadLockFile = (filePath: string) => {
+  const fileContent = fs.readFileSync(filePath, "utf8");
+  return JSON.parse(fileContent);
+};
+
+export const saveLockFile = (
+  filePath: string,
+  actionName: string,
+  version: string
+) => {
+  fs.writeFileSync(filePath, JSON.stringify({ actionName, version }, null, 2));
+};

js/src/sdk/utils/lockFile.ts

@@ -0,0 +1,60 @@
+import logger from "../../utils/logger";
+
+export const updateLockFileWithActionVersion = (
+  filePath: string,
+  actionName: string,
+  version: string
+) => {
+  const actionVersions = getVersionsFromLockFileAsJson(filePath);
+  actionVersions[actionName] = version;
+  saveLockFile(filePath, actionVersions);
+};
+
+export const getVersionsFromLockFileAsJson = (filePath: string) => {
+  try {
+    const lockFileContent = require("fs").readFileSync(filePath, "utf8");
+    const actionVersions: Record<string, string> = {};
+    const lines = lockFileContent.split("\n");
+    for (const line of lines) {
+      if (line) {
+        const [actionName, version] = line.split("=");
+        actionVersions[actionName] = version;
+      }
+    }
+    return actionVersions;
+  } catch (e) {
+    const error = e as NodeJS.ErrnoException;
+    if (error.code === "ENOENT") {
+      logger.warn("Lock file does not exist, creating new one");
+    } else if (error.code === "EACCES" || error.code === "EPERM") {
+      logger.error("Permission denied accessing lock file", e);
+    } else {
+      logger.warn("Error reading lock file", e);
+    }
+    return {};
+  }
+};
+
+export const saveLockFile = (
+  filePath: string,
+  actionVersions: Record<string, string>
+) => {
+  try {
+    const lockFileContent = Object.entries(actionVersions)
+      .map(([actionName, version]) => `${actionName}=${version}`)
+      .join("\n");
+    require("fs").writeFileSync(filePath, lockFileContent);
+  } catch (e) {
+    const error = e as NodeJS.ErrnoException;
+    if (error.code === "EACCES" || error.code === "EPERM") {
+      logger.error("Permission denied writing to lock file", e);
+      throw new Error("Permission denied writing to lock file");
+    } else if (error.code === "ENOENT") {
+      logger.error("Directory does not exist for lock file", e);
+      throw new Error("Directory does not exist for lock file");
+    } else {
+      logger.error("Error writing to lock file", e);
+      throw new Error("Error writing to lock file");
+    }
+  }
+};

js/src/sdk/utils/processor/action_lock.ts

@@ -0,0 +1,19 @@
+import { RawActionData } from "../../../types/base_toolset";
+import { updateLockFileWithActionVersion } from "../lockFile";
+
+export const actionLockProcessor = (
+  filePath: string,
+  {
+    actionName,
+    toolSchema,
+  }: {
+    actionName: string;
+    toolSchema: RawActionData;
+  }
+): RawActionData => {
+  const version = toolSchema.version;
+
+  updateLockFileWithActionVersion(filePath, actionName, version);
+
+  return toolSchema;
+};

js/src/types/base_toolset.ts

@@ -27,6 +27,8 @@ export const ZRawActionSchema = z.object({
     name: z.string(),
     toolName: z.string().optional(),
   }),
+  version: z.string().optional(),
+  availableVersions: z.array(z.string()).optional(),
 });
 
 export type RawActionData = z.infer<typeof ZRawActionSchema>;