zapier-platform-cli 16.3.1 → 16.5.0

package/oclif.manifest.json

@@ -178,11 +178,18 @@
           "required": true
         }
       },
-      "description": "Mark a non-production version of your integration as deprecated, with removal by a certain date.\n\nUse this when an integration version will not be supported or start breaking at a known date.\n\nZapier will send an email warning users of the deprecation once a date is set, they'll start seeing it as \"Deprecated\" in the UI, and once the deprecation date arrives, if the Zaps weren't updated, they'll be paused and the users will be emailed again explaining what happened.\n\nAfter the deprecation date has passed it will be safe to delete that integration version.\n\nDo not use this if you have non-breaking changes, such as fixing help text.",
+      "description": "Mark a non-production version of your integration as deprecated, with removal by a certain date.\n\nUse this when an integration version will not be supported or start breaking at a known date.\n\nZapier will immediately send emails warning users of the deprecation if a date less than 30 days in the future is set, otherwise the emails will be sent exactly 30 days before the configured deprecation date.\n\nThere are other side effects: they'll start seeing it as \"Deprecated\" in the UI, and once the deprecation date arrives, if the Zaps weren't updated, they'll be paused and the users will be emailed again explaining what happened.\n\nDo not use deprecation if you only have non-breaking changes, such as:\n- Fixing help text\n- Adding new triggers/actions\n- Improving existing functionality\n- other bug fixes that don't break existing automations.",
       "examples": [
         "zapier deprecate 1.2.3 2011-10-01"
       ],
       "flags": {
+        "force": {
+          "char": "f",
+          "description": "Skip confirmation prompt. Use with caution.",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "debug": {
           "char": "d",
           "description": "Show extra debugging output.",
@@ -459,7 +466,7 @@
           "name": "actionKey"
         }
       },
-      "description": "Invoke an auth operation, a trigger, or a create/search action locally.\n\nThis command emulates how Zapier production environment would invoke your integration. It runs code locally, so you can use this command to quickly test your integration without deploying it to Zapier. This is especially useful for debugging and development.\n\nThis command loads environment variables and `authData` from the `.env` file in the current directory. If you don't have a `.env` file yet, you can use the `zapier invoke auth start` command to help you initialize it, or you can manually create it.\n\nThe `zapier invoke auth start` subcommand will prompt you for the necessary auth fields and save them to the `.env` file. For OAuth2, it will start a local HTTP server, open the authorization URL in the browser, wait for the OAuth2 redirect, and get the access token.\n\nEach line in the `.env` file should follow one of these formats:\n\n* `VAR_NAME=VALUE` for environment variables\n* `authData_FIELD_KEY=VALUE` for auth data fields\n\nFor example, a `.env` file for an OAuth2 integration might look like this:\n\n```\nCLIENT_ID='your_client_id'\nCLIENT_SECRET='your_client_secret'\nauthData_access_token='1234567890'\nauthData_refresh_token='abcdefg'\nauthData_account_name='zapier'\n```\n\nTo test if the auth data is correct, run either one of these:\n\n```\nzapier invoke auth test   # invokes authentication.test method\nzapier invoke auth label  # invokes authentication.test and renders connection label\n```\n\nTo refresh stale auth data for OAuth2 or session auth, run `zapier invoke auth refresh`.\n\nOnce you have the correct auth data, you can test an trigger, a search, or a create action. For example, here's how you invoke a trigger with the key `new_recipe`:\n\n```\nzapier invoke trigger new_recipe\n```\n\nTo add input data, use the `--inputData` flag. The input data can come from the command directly, a file, or stdin. See **EXAMPLES** below.\n\nWhen you miss any command arguments, such as ACTIONTYPE or ACTIONKEY, the command will prompt you interactively. If you don't want to get interactive prompts, use the `--non-interactive` flag.\n\nThe `--debug` flag will show you the HTTP request logs and any console logs you have in your code.\n\nThe following is a non-exhaustive list of current limitations and may be supported in the future:\n\n- Hook triggers, including REST hook subscribe/unsubscribe\n- Line items\n- Output hydration\n- File upload\n- Dynamic dropdown pagination\n- Function-based connection label\n- Buffered create actions\n- Search-or-create actions\n- Search-powered fields\n- Field choices\n- autoRefresh for OAuth2 and session auth\n",
+      "description": "Invoke an auth operation, a trigger, or a create/search action locally.\n\nThis command emulates how Zapier production environment would invoke your integration. It runs code locally, so you can use this command to quickly test your integration without deploying it to Zapier. This is especially useful for debugging and development.\n\nWhy use this command?\n\n* Fast feedback loop: Write code and run this command to verify if it works immediately\n* Step-by-step debugging: Running locally means you can use a debugger to step through your code\n* Untruncated logs: View complete logs and errors in your terminal\n\n### Authentication\n\nYou can supply the authentcation data in two ways: Load from the local `.env` file or use the (experimental) `--authentication-id` flag.\n\n#### The local `.env` file\n\nThis command loads environment variables and `authData` from the `.env` file in the current directory. If you don't have a `.env` file yet, you can use the `zapier invoke auth start` command to help you initialize it, or you can manually create it.\n\nThe `zapier invoke auth start` subcommand will prompt you for the necessary auth fields and save them to the `.env` file. For OAuth2, it will start a local HTTP server, open the authorization URL in the browser, wait for the OAuth2 redirect, and get the access token.\n\nEach line in the `.env` file should follow one of these formats:\n\n* `VAR_NAME=VALUE` for environment variables\n* `authData_FIELD_KEY=VALUE` for auth data fields\n\nFor example, a `.env` file for an OAuth2 integration might look like this:\n\n```\nCLIENT_ID='your_client_id'\nCLIENT_SECRET='your_client_secret'\nauthData_access_token='1234567890'\nauthData_refresh_token='abcdefg'\nauthData_account_name='zapier'\n```\n\n\n#### The `--authentication-id` flag (EXPERIMENTAL)\n\nSetting up local auth data can be troublesome. You'd have to configure your app server to allow localhost redirect URIs or use a port forwarding tool. This is sometimes not easy to get right.\n\nThe `--authentication-id` flag (`-a` for short) gives you an alternative (and perhaps easier) way to supply your auth data. You can use `-a` to specify an existing production authentication/connection. The available authentications can be found at https://zapier.com/app/assets/connections. Check https://zpr.io/z8SjFTdnTFZ2 for more instructions.\n\nWhen `-a -` is specified, such as `zapier invoke auth test -a -`, the command will interactively prompt you to select one of your available authentications.\n\nIf you know your authentication ID, you can specify it directly, such as `zapier invoke auth test -a 123456`.\n\n#### Testing authentication\n\nTo test if the auth data is correct, run either one of these:\n\n```\nzapier invoke auth test   # invokes authentication.test method\nzapier invoke auth label  # invokes authentication.test and renders connection label\n```\n\nTo refresh stale auth data for OAuth2 or session auth, run `zapier invoke auth refresh`. Note that refreshing is only applicable for local auth data in the `.env` file.\n\n### Invoking a trigger or an action\n\nOnce you have the correct auth data, you can test an trigger, a search, or a create action. For example, here's how you invoke a trigger with the key `new_recipe`:\n\n```\nzapier invoke trigger new_recipe\n```\n\nTo add input data, use the `--inputData` flag (`-i` for short). The input data can come from the command directly, a file, or stdin. See **EXAMPLES** below.\n\nWhen you miss any command arguments, such as ACTIONTYPE or ACTIONKEY, the command will prompt you interactively. If you don't want to get interactive prompts, use the `--non-interactive` flag.\n\nThe `--debug` flag will show you the HTTP request logs and any console logs you have in your code.\n\n### Limitations\n\nThe following is a non-exhaustive list of current limitations and may be supported in the future:\n\n- Hook triggers, including REST hook subscribe/unsubscribe\n- Line items\n- Output hydration\n- File upload\n- Dynamic dropdown pagination\n- Function-based connection label\n- Buffered create actions\n- Search-or-create actions\n- Search-powered fields\n- Field choices\n- autoRefresh for OAuth2 and session auth\n",
       "examples": [
         "zapier invoke",
         "zapier invoke auth start",
@@ -468,8 +475,10 @@
         "zapier invoke auth label",
         "zapier invoke trigger new_recipe",
         "zapier invoke create add_recipe --inputData '{\"title\": \"Pancakes\"}'",
-        "zapier invoke search find_recipe -i @file.json",
-        "cat file.json | zapier invoke trigger new_recipe -i @-"
+        "zapier invoke search find_recipe -i @file.json --non-interactive",
+        "cat file.json | zapier invoke trigger new_recipe -i @-",
+        "zapier invoke search find_ticket --authentication-id 12345",
+        "zapier invoke create add_ticket -a -"
       ],
       "flags": {
         "inputData": {
@@ -546,6 +555,14 @@
           "multiple": false,
           "type": "option"
         },
+        "authentication-id": {
+          "char": "a",
+          "description": "EXPERIMENTAL: Instead of using the local .env file, use the production authentication data with the given authentication ID (aka the \"app connection\" on Zapier). Find them at https://zapier.com/app/assets/connections (https://zpr.io/z8SjFTdnTFZ2 for instructions) or specify '-' to interactively select one from your available authentications. When specified, the code will still run locally, but all outgoing requests will be proxied through Zapier with the production auth data.",
+          "name": "authentication-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "debug": {
           "char": "d",
           "description": "Show extra debugging output.",
@@ -632,6 +649,58 @@
         "jobs.js"
       ]
     },
+    "legacy": {
+      "aliases": [],
+      "args": {
+        "version": {
+          "description": "The version to mark as legacy.",
+          "name": "version",
+          "required": true
+        }
+      },
+      "description": "Mark a non-production version of your integration as legacy.\n\nUse this when an integration version is no longer recommended for new users, but you don't want to block existing users from using it.\n\nReasons why you might want to mark a version as legacy:\n- this version may be discontinued in the future\n- this version has bugs\n- a newer version has been released and you want to encourage users to upgrade\n\n",
+      "examples": [
+        "zapier legacy 1.2.3"
+      ],
+      "flags": {
+        "force": {
+          "char": "f",
+          "description": "Skip confirmation prompt. Use with caution.",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "debug": {
+          "char": "d",
+          "description": "Show extra debugging output.",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "invokedFromAnotherCommand": {
+          "hidden": true,
+          "name": "invokedFromAnotherCommand",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "legacy",
+      "pluginAlias": "zapier-platform-cli",
+      "pluginName": "zapier-platform-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "skipValidInstallCheck": true,
+      "isESM": false,
+      "relativePath": [
+        "src",
+        "oclif",
+        "commands",
+        "legacy.js"
+      ]
+    },
     "link": {
       "aliases": [],
       "args": {},
@@ -1444,7 +1513,7 @@
     "versions": {
       "aliases": [],
       "args": {},
-      "description": "List the versions of your integration available for use in the Zapier editor.",
+      "description": "List the versions of your integration available for use in Zapier automations.",
       "flags": {
         "debug": {
           "char": "d",
@@ -1493,54 +1562,6 @@
         "versions.js"
       ]
     },
-    "cache:clear": {
-      "aliases": [],
-      "args": {
-        "majorVersion": {
-          "description": "(Optional) The cache data will be deleted for this major version. If not provided, you must pick from a list of major versions for this integration.",
-          "name": "majorVersion",
-          "required": false
-        }
-      },
-      "description": "Clear the cache data for a major version. \n\nThis command clears the cache data for a major version of your integration.\nThe job will be run in the background and may take some time to complete.\nYou can check `zapier history` to see the job status.\n",
-      "examples": [
-        "zapier cache:clear",
-        "zapier cache:clear 2"
-      ],
-      "flags": {
-        "debug": {
-          "char": "d",
-          "description": "Show extra debugging output.",
-          "name": "debug",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "invokedFromAnotherCommand": {
-          "hidden": true,
-          "name": "invokedFromAnotherCommand",
-          "allowNo": false,
-          "type": "boolean"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "cache:clear",
-      "pluginAlias": "zapier-platform-cli",
-      "pluginName": "zapier-platform-cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "skipValidInstallCheck": true,
-      "hide": true,
-      "isESM": false,
-      "relativePath": [
-        "src",
-        "oclif",
-        "commands",
-        "cache",
-        "clear.js"
-      ]
-    },
     "canary:create": {
       "aliases": [],
       "args": {
@@ -1704,18 +1725,19 @@
         "list.js"
       ]
     },
-    "env:get": {
+    "cache:clear": {
       "aliases": [],
       "args": {
-        "version": {
-          "description": "The version to get the environment for.",
-          "name": "version",
-          "required": true
+        "majorVersion": {
+          "description": "(Optional) The cache data will be deleted for this major version. If not provided, you must pick from a list of major versions for this integration.",
+          "name": "majorVersion",
+          "required": false
         }
       },
-      "description": "Get environment variables for a version.",
+      "description": "Clear the cache data for a major version. \n\nThis command clears the cache data for a major version of your integration.\nThe job will be run in the background and may take some time to complete.\nYou can check `zapier history` to see the job status.\n",
       "examples": [
-        "zapier env:get 1.2.3"
+        "zapier cache:clear",
+        "zapier cache:clear 2"
       ],
       "flags": {
         "debug": {
@@ -1725,21 +1747,45 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "format": {
-          "char": "f",
-          "description": "Change the way structured data is presented. If \"json\" or \"raw\", you can pipe the output of the command into other tools, such as jq.",
-          "name": "format",
-          "default": "table",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "options": [
-            "plain",
-            "json",
-            "raw",
-            "row",
-            "table"
-          ],
-          "type": "option"
+        "invokedFromAnotherCommand": {
+          "hidden": true,
+          "name": "invokedFromAnotherCommand",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "cache:clear",
+      "pluginAlias": "zapier-platform-cli",
+      "pluginName": "zapier-platform-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "skipValidInstallCheck": true,
+      "hide": true,
+      "isESM": false,
+      "relativePath": [
+        "src",
+        "oclif",
+        "commands",
+        "cache",
+        "clear.js"
+      ]
+    },
+    "delete:integration": {
+      "aliases": [
+        "delete:app"
+      ],
+      "args": {},
+      "description": "Delete your integration (including all versions).\n\nThis only works if there are no active users or Zaps on any version. If you only want to delete certain versions, use the `zapier delete:version` command instead. It's unlikely that you'll be able to run this on an app that you've pushed publicly, since there are usually still users.",
+      "flags": {
+        "debug": {
+          "char": "d",
+          "description": "Show extra debugging output.",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
         },
         "invokedFromAnotherCommand": {
           "hidden": true,
@@ -1750,7 +1796,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "env:get",
+      "id": "delete:integration",
       "pluginAlias": "zapier-platform-cli",
       "pluginName": "zapier-platform-cli",
       "pluginType": "core",
@@ -1762,35 +1808,21 @@
         "src",
         "oclif",
         "commands",
-        "env",
-        "get.js"
+        "delete",
+        "integration.js"
       ]
     },
-    "env:set": {
+    "delete:version": {
       "aliases": [],
       "args": {
         "version": {
-          "description": "The version to set the environment for. Values are copied forward when a new version is created, but this command will only ever affect the specified version.",
+          "description": "Specify the version to delete. It must have no users or Zaps.",
           "name": "version",
           "required": true
-        },
-        "key-value pairs...": {
-          "description": "The key-value pairs to set. Keys are case-insensitive. Each pair should be space separated and pairs should be separated by an `=`. For example: `A=123 B=456`",
-          "name": "key-value pairs..."
         }
       },
-      "description": "Set environment variables for a version.",
-      "examples": [
-        "zapier env:set 1.2.3 SECRET=12345 OTHER=4321"
-      ],
+      "description": "Delete a specific version of your integration.\n\nThis only works if there are no users or Zaps on that version. You will probably need to have run `zapier migrate` and `zapier deprecate` before this command will work.",
       "flags": {
-        "force": {
-          "char": "f",
-          "description": "Force the update of environment variables regardless if the app version is production or not. Use with caution.",
-          "name": "force",
-          "allowNo": false,
-          "type": "boolean"
-        },
         "debug": {
           "char": "d",
           "description": "Show extra debugging output.",
@@ -1807,11 +1839,11 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "env:set",
+      "id": "delete:version",
       "pluginAlias": "zapier-platform-cli",
       "pluginName": "zapier-platform-cli",
       "pluginType": "core",
-      "strict": false,
+      "strict": true,
       "enableJsonFlag": false,
       "skipValidInstallCheck": true,
       "isESM": false,
@@ -1819,35 +1851,24 @@
         "src",
         "oclif",
         "commands",
-        "env",
-        "set.js"
+        "delete",
+        "version.js"
       ]
     },
-    "env:unset": {
+    "env:get": {
       "aliases": [],
       "args": {
         "version": {
-          "description": "The version to set the environment for.",
+          "description": "The version to get the environment for.",
           "name": "version",
           "required": true
-        },
-        "keys...": {
-          "description": "The keys to unset. Keys are case-insensitive.",
-          "name": "keys..."
         }
       },
-      "description": "Unset environment variables for a version.",
+      "description": "Get environment variables for a version.",
       "examples": [
-        "zapier env:unset 1.2.3 SECRET OTHER"
+        "zapier env:get 1.2.3"
       ],
       "flags": {
-        "force": {
-          "char": "f",
-          "description": "Force the update of environment variables regardless if the app version is production or not. Use with caution.",
-          "name": "force",
-          "allowNo": false,
-          "type": "boolean"
-        },
         "debug": {
           "char": "d",
           "description": "Show extra debugging output.",
@@ -1855,6 +1876,22 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "format": {
+          "char": "f",
+          "description": "Change the way structured data is presented. If \"json\" or \"raw\", you can pipe the output of the command into other tools, such as jq.",
+          "name": "format",
+          "default": "table",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "plain",
+            "json",
+            "raw",
+            "row",
+            "table"
+          ],
+          "type": "option"
+        },
         "invokedFromAnotherCommand": {
           "hidden": true,
           "name": "invokedFromAnotherCommand",
@@ -1864,11 +1901,11 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "env:unset",
+      "id": "env:get",
       "pluginAlias": "zapier-platform-cli",
       "pluginName": "zapier-platform-cli",
       "pluginType": "core",
-      "strict": false,
+      "strict": true,
       "enableJsonFlag": false,
       "skipValidInstallCheck": true,
       "isESM": false,
@@ -1877,16 +1914,34 @@
         "oclif",
         "commands",
         "env",
-        "unset.js"
+        "get.js"
       ]
     },
-    "delete:integration": {
-      "aliases": [
-        "delete:app"
+    "env:set": {
+      "aliases": [],
+      "args": {
+        "version": {
+          "description": "The version to set the environment for. Values are copied forward when a new version is created, but this command will only ever affect the specified version.",
+          "name": "version",
+          "required": true
+        },
+        "key-value pairs...": {
+          "description": "The key-value pairs to set. Keys are case-insensitive. Each pair should be space separated and pairs should be separated by an `=`. For example: `A=123 B=456`",
+          "name": "key-value pairs..."
+        }
+      },
+      "description": "Set environment variables for a version.",
+      "examples": [
+        "zapier env:set 1.2.3 SECRET=12345 OTHER=4321"
       ],
-      "args": {},
-      "description": "Delete your integration (including all versions).\n\nThis only works if there are no active users or Zaps on any version. If you only want to delete certain versions, use the `zapier delete:version` command instead. It's unlikely that you'll be able to run this on an app that you've pushed publicly, since there are usually still users.",
       "flags": {
+        "force": {
+          "char": "f",
+          "description": "Force the update of environment variables regardless if the app version is production or not. Use with caution.",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "debug": {
           "char": "d",
           "description": "Show extra debugging output.",
@@ -1903,11 +1958,11 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "delete:integration",
+      "id": "env:set",
       "pluginAlias": "zapier-platform-cli",
       "pluginName": "zapier-platform-cli",
       "pluginType": "core",
-      "strict": true,
+      "strict": false,
       "enableJsonFlag": false,
       "skipValidInstallCheck": true,
       "isESM": false,
@@ -1915,21 +1970,35 @@
         "src",
         "oclif",
         "commands",
-        "delete",
-        "integration.js"
+        "env",
+        "set.js"
       ]
     },
-    "delete:version": {
+    "env:unset": {
       "aliases": [],
       "args": {
         "version": {
-          "description": "Specify the version to delete. It must have no users or Zaps.",
+          "description": "The version to set the environment for.",
           "name": "version",
           "required": true
+        },
+        "keys...": {
+          "description": "The keys to unset. Keys are case-insensitive.",
+          "name": "keys..."
         }
       },
-      "description": "Delete a specific version of your integration.\n\nThis only works if there are no users or Zaps on that version. You will probably need to have run `zapier migrate` and `zapier deprecate` before this command will work.",
+      "description": "Unset environment variables for a version.",
+      "examples": [
+        "zapier env:unset 1.2.3 SECRET OTHER"
+      ],
       "flags": {
+        "force": {
+          "char": "f",
+          "description": "Force the update of environment variables regardless if the app version is production or not. Use with caution.",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "debug": {
           "char": "d",
           "description": "Show extra debugging output.",
@@ -1946,11 +2015,11 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "delete:version",
+      "id": "env:unset",
       "pluginAlias": "zapier-platform-cli",
       "pluginName": "zapier-platform-cli",
       "pluginType": "core",
-      "strict": true,
+      "strict": false,
       "enableJsonFlag": false,
       "skipValidInstallCheck": true,
       "isESM": false,
@@ -1958,8 +2027,8 @@
         "src",
         "oclif",
         "commands",
-        "delete",
-        "version.js"
+        "env",
+        "unset.js"
       ]
     },
     "team:add": {
@@ -2341,5 +2410,5 @@
       ]
     }
   },
-  "version": "16.3.1"
+  "version": "16.5.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zapier-platform-cli",
-  "version": "16.3.1",
+  "version": "16.5.0",
   "description": "The CLI for managing integrations in Zapier Developer Platform.",
   "repository": "zapier/zapier-platform",
   "homepage": "https://platform.zapier.com/",

package/src/oclif/ZapierBaseCommand.js

@@ -18,7 +18,7 @@ class ZapierBaseCommand extends Command {
 
     if (this.flags.debug) {
       this.debug.enabled = true; // enables this.debug on the command
-      require('debug').enable('zapier:*'); // enables all further spawned functions, like API
+      require('debug').enable('zapier:*,oclif:zapier:*'); // enables all further spawned functions, like API
     }
 
     this.debug('argv is', this.argv);

package/src/oclif/commands/deprecate.js

@@ -1,15 +1,38 @@
 const BaseCommand = require('../ZapierBaseCommand');
-const { Args } = require('@oclif/core');
+const { Args, Flags } = require('@oclif/core');
 const { buildFlags } = require('../buildFlags');
+const colors = require('colors/safe');
 
-const { callAPI } = require('../../utils/api');
+const { callAPI, getSpecificVersionInfo } = require('../../utils/api');
 
 class DeprecateCommand extends BaseCommand {
   async perform() {
     const app = await this.getWritableApp();
     const { version, date } = this.args;
+
+    const versionInfo = await getSpecificVersionInfo(version);
+    const hasActiveUsers = versionInfo.user_count && versionInfo.user_count > 0;
+
+    this.log(
+      `${colors.yellow('Warning: Deprecation is an irreversible action that will eventually block access to this version.')}\n` +
+        `${colors.yellow('If all your changes are non-breaking, use `zapier migrate` instead to move users over to a newer version.')}\n`,
+    );
+
+    if (
+      !this.flags.force &&
+      !(await this.confirm(
+        'Are you sure you want to deprecate this version? This will notify users that their Zaps or other automations will stop working after the specified date.' +
+          (hasActiveUsers
+            ? `\n\nThis version has ${versionInfo.user_count} active user(s). Strongly consider migrating users to another version before deprecating!`
+            : ''),
+      ))
+    ) {
+      this.log('\nDeprecation cancelled.');
+      return;
+    }
+
     this.log(
-      `Preparing to deprecate version ${version} your app "${app.title}".\n`,
+      `\nPreparing to deprecate version ${version} your app "${app.title}".\n`,
     );
     const url = `/apps/${app.id}/versions/${version}/deprecate`;
     this.startSpinner(`Deprecating ${version}`);
@@ -21,12 +44,19 @@ class DeprecateCommand extends BaseCommand {
     });
     this.stopSpinner();
     this.log(
-      `\nWe'll let users know that this version is no longer recommended and will cease to work on ${date}.`,
+      `\nWe'll let users know that this version will cease to work on ${date}.`,
     );
   }
 }
 
-DeprecateCommand.flags = buildFlags();
+DeprecateCommand.flags = buildFlags({
+  commandFlags: {
+    force: Flags.boolean({
+      char: 'f',
+      description: 'Skip confirmation prompt. Use with caution.',
+    }),
+  },
+});
 DeprecateCommand.args = {
   version: Args.string({
     description: 'The version to deprecate.',
@@ -43,11 +73,15 @@ DeprecateCommand.description = `Mark a non-production version of your integratio
 
 Use this when an integration version will not be supported or start breaking at a known date.
 
-Zapier will send an email warning users of the deprecation once a date is set, they'll start seeing it as "Deprecated" in the UI, and once the deprecation date arrives, if the Zaps weren't updated, they'll be paused and the users will be emailed again explaining what happened.
+Zapier will immediately send emails warning users of the deprecation if a date less than 30 days in the future is set, otherwise the emails will be sent exactly 30 days before the configured deprecation date.
 
-After the deprecation date has passed it will be safe to delete that integration version.
+There are other side effects: they'll start seeing it as "Deprecated" in the UI, and once the deprecation date arrives, if the Zaps weren't updated, they'll be paused and the users will be emailed again explaining what happened.
 
-Do not use this if you have non-breaking changes, such as fixing help text.`;
+Do not use deprecation if you only have non-breaking changes, such as:
+- Fixing help text
+- Adding new triggers/actions
+- Improving existing functionality
+- other bug fixes that don't break existing automations.`;
 DeprecateCommand.skipValidInstallCheck = true;
 
 module.exports = DeprecateCommand;