zapier-platform-cli 16.3.1 → 16.4.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.",
@@ -2341,5 +2358,5 @@
       ]
     }
   },
-  "version": "16.3.1"
+  "version": "16.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zapier-platform-cli",
-  "version": "16.3.1",
+  "version": "16.4.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;

package/src/oclif/commands/invoke.js

@@ -15,6 +15,12 @@ const BaseCommand = require('../ZapierBaseCommand');
 const { buildFlags } = require('../buildFlags');
 const { localAppCommand, getLocalAppHandler } = require('../../utils/local');
 const { startSpinner, endSpinner } = require('../../utils/display');
+const {
+  getLinkedAppConfig,
+  listAuthentications,
+  readCredentials,
+} = require('../../utils/api');
+const { AUTH_KEY } = require('../../constants');
 
 const ACTION_TYPE_PLURALS = {
   trigger: 'triggers',
@@ -235,9 +241,88 @@ const appendEnv = async (vars, prefix = '') => {
   );
 };
 
-const testAuth = async (authData, meta, zcacheTestObj) => {
+const replaceDoubleCurlies = async (request) => {
+  // Use lcurly-fieldName-rcurly instead of {{fieldName}} to bypass node-fetch's
+  // URL validation in case the variable is used in a URL.
+  if (request.url) {
+    request.url = request.url
+      .replaceAll('{{', 'lcurly-')
+      .replaceAll('}}', '-rcurly');
+  }
+
+  // The authorization header may confuse zapier.com and it's relay's job to add
+  // it, so we delete it here.
+  delete request.headers.authorization;
+  delete request.headers.Authorization;
+
+  return request;
+};
+
+const restoreDoubleCurlies = async (response) => {
+  if (response.url) {
+    response.url = response.url
+      .replaceAll('lcurly-', '{{')
+      .replaceAll('-rcurly', '}}');
+  }
+  if (response.request?.url) {
+    response.request.url = response.request.url
+      .replaceAll('lcurly-', '{{')
+      .replaceAll('-rcurly', '}}');
+  }
+  return response;
+};
+
+const localAppCommandWithRelayErrorHandler = async (args) => {
+  if (args.relayAuthenticationId) {
+    args = {
+      ...args,
+      beforeRequest: [replaceDoubleCurlies],
+      afterResponse: [restoreDoubleCurlies],
+    };
+  }
+
+  let output;
+  try {
+    output = await localAppCommand(args);
+  } catch (outerError) {
+    if (outerError.name === 'ResponseError') {
+      let response;
+      try {
+        response = JSON.parse(outerError.message);
+      } catch (innerError) {
+        throw outerError;
+      }
+      if (typeof response.content === 'string') {
+        const match = response.content.match(/domain filter `([^`]+)`/);
+        if (!match) {
+          throw outerError;
+        }
+        const domainFilter = match[1];
+        const requestUrl = response.request.url
+          .replaceAll('lcurly-', '{{')
+          .replaceAll('-rcurly', '}}');
+        throw new Error(
+          `Request to ${requestUrl} was blocked. ` +
+            `Only these domain names are allowed: ${domainFilter}. ` +
+            'Contact Zapier team to verify your domain filter setting.',
+        );
+      }
+    }
+    throw outerError;
+  }
+  return output;
+};
+
+const testAuth = async (
+  authId,
+  authData,
+  meta,
+  zcacheTestObj,
+  appId,
+  deployKey,
+) => {
   startSpinner('Invoking authentication.test');
-  const result = await localAppCommand({
+  const result = await localAppCommandWithRelayErrorHandler({
     command: 'execute',
     method: 'authentication.test',
     bundle: {
@@ -250,13 +335,31 @@ const testAuth = async (authData, meta, zcacheTestObj) => {
     zcacheTestObj,
     customLogger,
     calledFromCliInvoke: true,
+    appId,
+    deployKey,
+    relayAuthenticationId: authId,
   });
   endSpinner();
   return result;
 };
 
-const getAuthLabel = async (labelTemplate, authData, meta, zcacheTestObj) => {
-  const testResult = await testAuth(authData, meta, zcacheTestObj);
+const getAuthLabel = async (
+  labelTemplate,
+  authId,
+  authData,
+  meta,
+  zcacheTestObj,
+  appId,
+  deployKey,
+) => {
+  const testResult = await testAuth(
+    authId,
+    authData,
+    meta,
+    zcacheTestObj,
+    appId,
+    deployKey,
+  );
   labelTemplate = labelTemplate.replace('__', '.');
   const tpl = _.template(labelTemplate, { interpolate: /{{([\s\S]+?)}}/g });
   return tpl({ ...testResult, bundle: { authData, inputData: testResult } });
@@ -632,10 +735,13 @@ class InvokeCommand extends BaseCommand {
     field,
     appDefinition,
     inputData,
+    authId,
     authData,
     timezone,
     zcacheTestObj,
     cursorTestObj,
+    appId,
+    deployKey,
   ) {
     const message = formatFieldDisplay(field) + ':';
     if (field.dynamic) {
@@ -655,16 +761,19 @@ class InvokeCommand extends BaseCommand {
         'triggers',
         trigger,
         inputData,
+        authId,
         authData,
         meta,
         timezone,
         zcacheTestObj,
         cursorTestObj,
+        appId,
+        deployKey,
       );
       return this.promptWithList(
         message,
         choices.map((c) => {
-          const id = c[idField] || 'null';
+          const id = c[idField] ?? 'null';
           const label = getLabelForDynamicDropdown(c, labelField, idField);
           return {
             name: `${label} (${id})`,
@@ -685,11 +794,14 @@ class InvokeCommand extends BaseCommand {
     inputData,
     inputFields,
     appDefinition,
+    authId,
     authData,
     meta,
     timezone,
     zcacheTestObj,
     cursorTestObj,
+    appId,
+    deployKey,
   ) {
     const missingFields = getMissingRequiredInputFields(inputData, inputFields);
     if (missingFields.length) {
@@ -704,10 +816,13 @@ class InvokeCommand extends BaseCommand {
           f,
           appDefinition,
           inputData,
+          authId,
           authData,
           timezone,
           zcacheTestObj,
           cursorTestObj,
+          appId,
+          deployKey,
         );
       }
     }
@@ -717,10 +832,13 @@ class InvokeCommand extends BaseCommand {
     inputData,
     inputFields,
     appDefinition,
+    authId,
     authData,
     timezone,
     zcacheTestObj,
     cursorTestObj,
+    appId,
+    deployKey,
   ) {
     inputFields = inputFields.filter((f) => f.key);
     if (!inputFields.length) {
@@ -768,10 +886,13 @@ class InvokeCommand extends BaseCommand {
         field,
         appDefinition,
         inputData,
+        authId,
         authData,
         timezone,
         zcacheTestObj,
         cursorTestObj,
+        appId,
+        deployKey,
       );
     }
   }
@@ -780,31 +901,40 @@ class InvokeCommand extends BaseCommand {
     inputData,
     inputFields,
     appDefinition,
+    authId,
     authData,
     meta,
     timezone,
     zcacheTestObj,
     cursorTestObj,
+    appId,
+    deployKey,
   ) {
     await this.promptOrErrorForRequiredInputFields(
       inputData,
       inputFields,
       appDefinition,
+      authId,
       authData,
       meta,
       timezone,
       zcacheTestObj,
       cursorTestObj,
+      appId,
+      deployKey,
     );
     if (!this.nonInteractive && !meta.isFillingDynamicDropdown) {
       await this.promptForInputFieldEdit(
         inputData,
         inputFields,
         appDefinition,
+        authId,
         authData,
         timezone,
         zcacheTestObj,
         cursorTestObj,
+        appId,
+        deployKey,
       );
     }
   }
@@ -814,11 +944,14 @@ class InvokeCommand extends BaseCommand {
     actionTypePlural,
     action,
     inputData,
+    authId,
     authData,
     meta,
     timezone,
     zcacheTestObj,
     cursorTestObj,
+    appId,
+    deployKey,
   ) {
     // Do these in order:
     // 1. Prompt for static input fields that alter dynamic fields
@@ -835,17 +968,20 @@ class InvokeCommand extends BaseCommand {
       inputData,
       staticInputFields,
       appDefinition,
+      authId,
       authData,
       meta,
       timezone,
       zcacheTestObj,
       cursorTestObj,
+      appId,
+      deployKey,
     );
 
     let methodName = `${actionTypePlural}.${action.key}.operation.inputFields`;
     startSpinner(`Invoking ${methodName}`);
 
-    const inputFields = await localAppCommand({
+    const inputFields = await localAppCommandWithRelayErrorHandler({
       command: 'execute',
       method: methodName,
       bundle: {
@@ -857,6 +993,9 @@ class InvokeCommand extends BaseCommand {
       cursorTestObj,
       customLogger,
       calledFromCliInvoke: true,
+      appId,
+      deployKey,
+      relayAuthenticationId: authId,
     });
     endSpinner();
 
@@ -867,11 +1006,14 @@ class InvokeCommand extends BaseCommand {
         inputData,
         inputFields,
         appDefinition,
+        authId,
         authData,
         meta,
         timezone,
         zcacheTestObj,
         cursorTestObj,
+        appId,
+        deployKey,
       );
     }
 
@@ -879,7 +1021,7 @@ class InvokeCommand extends BaseCommand {
     methodName = `${actionTypePlural}.${action.key}.operation.perform`;
 
     startSpinner(`Invoking ${methodName}`);
-    const output = await localAppCommand({
+    const output = await localAppCommandWithRelayErrorHandler({
       command: 'execute',
       method: methodName,
       bundle: {
@@ -891,15 +1033,40 @@ class InvokeCommand extends BaseCommand {
       cursorTestObj,
       customLogger,
       calledFromCliInvoke: true,
+      appId,
+      deployKey,
+      relayAuthenticationId: authId,
     });
     endSpinner();
 
     return output;
   }
 
+  async promptForAuthentication() {
+    const auths = (await listAuthentications()).authentications;
+    if (!auths || auths.length === 0) {
+      throw new Error(
+        'No authentications/connections found for your integration. ' +
+          'Add a new connection at https://zapier.com/app/assets/connections ' +
+          'or use local auth data by removing the `--authentication-id` flag.',
+      );
+    }
+    const authChoices = auths.map((auth) => ({
+      name: `${auth.title} | ${auth.app_version} | ID: ${auth.id}`,
+      value: auth.id,
+    }));
+    return this.promptWithList(
+      'Which authentication/connection would you like to use?',
+      authChoices,
+      { useStderr: true },
+    );
+  }
+
   async perform() {
+    let authId = this.flags['authentication-id'];
+
     const dotenvResult = dotenv.config({ override: true });
-    if (_.isEmpty(dotenvResult.parsed)) {
+    if (!authId && _.isEmpty(dotenvResult.parsed)) {
       console.warn(
         'The .env file does not exist or is empty. ' +
           'You may need to set some environment variables in there if your code uses process.env.',
@@ -955,10 +1122,37 @@ class InvokeCommand extends BaseCommand {
       }
     }
 
-    const authData = loadAuthDataFromEnv();
+    const appId = (await getLinkedAppConfig(null, false))?.id;
+    const deployKey = (await readCredentials(false))[AUTH_KEY];
+
+    if (authId === '-' || authId === '') {
+      if (this.nonInteractive) {
+        throw new Error(
+          "You cannot specify '-' or an empty string for `--authentication-id` in non-interactive mode.",
+        );
+      }
+      authId = (await this.promptForAuthentication()).toString();
+    }
+
     const zcacheTestObj = {};
     const cursorTestObj = {};
 
+    let authData = {};
+    if (authId) {
+      // Fill authData with curlies if we're in relay mode
+      const authFields = appDefinition.authentication.fields || [];
+      for (const field of authFields) {
+        if (field.key) {
+          authData[field.key] = `{{${field.key}}}`;
+        }
+      }
+    }
+
+    // Load from .env as well even in relay mode, in case the integration code
+    // assumes there are values in bundle.authData. Loading from .env at least
+    // gives the developer an option to override the values in bundle.authData.
+    authData = { ...authData, ...loadAuthDataFromEnv() };
+
     if (actionType === 'auth') {
       const meta = {
         isLoadingSample: false,
@@ -970,6 +1164,13 @@ class InvokeCommand extends BaseCommand {
       };
       switch (actionKey) {
         case 'start': {
+          if (authId) {
+            throw new Error(
+              'The `--authentication-id` flag is not applicable. ' +
+                'The `auth start` subcommand is to initialize local auth data in the .env file, ' +
+                'whereas `--authentication-id` is for proxying requests using production auth data.',
+            );
+          }
           const newAuthData = await this.startAuth(
             appDefinition,
             zcacheTestObj,
@@ -984,6 +1185,13 @@ class InvokeCommand extends BaseCommand {
           return;
         }
         case 'refresh': {
+          if (authId) {
+            throw new Error(
+              'The `--authentication-id` flag is not applicable. ' +
+                'The `auth refresh` subcommand can only refresh your local auth data in the .env file. ' +
+                'You might want to run `auth test` instead, which tests and may refresh auth data with the specified authentication ID in production.',
+            );
+          }
           const newAuthData = await this.refreshAuth(
             appDefinition,
             authData,
@@ -999,7 +1207,14 @@ class InvokeCommand extends BaseCommand {
           return;
         }
         case 'test': {
-          const output = await testAuth(authData, meta, zcacheTestObj);
+          const output = await testAuth(
+            authId,
+            authData,
+            meta,
+            zcacheTestObj,
+            appId,
+            deployKey,
+          );
           console.log(JSON.stringify(output, null, 2));
           return;
         }
@@ -1009,14 +1224,24 @@ class InvokeCommand extends BaseCommand {
             console.warn(
               'Function-based connection label is not supported yet. Printing auth test result instead.',
             );
-            const output = await testAuth(authData, meta, zcacheTestObj);
+            const output = await testAuth(
+              authId,
+              authData,
+              meta,
+              zcacheTestObj,
+              appId,
+              deployKey,
+            );
             console.log(JSON.stringify(output, null, 2));
           } else {
             const output = await getAuthLabel(
               labelTemplate,
+              authId,
               authData,
               meta,
               zcacheTestObj,
+              appId,
+              deployKey,
             );
             if (output) {
               console.log(output);
@@ -1085,11 +1310,14 @@ class InvokeCommand extends BaseCommand {
         actionTypePlural,
         action,
         inputData,
+        authId,
         authData,
         meta,
         timezone,
         zcacheTestObj,
         cursorTestObj,
+        appId,
+        deployKey,
       );
       console.log(JSON.stringify(output, null, 2));
     }
@@ -1149,6 +1377,11 @@ InvokeCommand.flags = buildFlags({
         'Only used by `auth start` subcommand. The local port that will be used to start the local HTTP server to listen for the OAuth2 callback. This port can be different from the one in the redirect URI if you have port forwarding set up.',
       default: 9000,
     }),
+    'authentication-id': Flags.string({
+      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.',
+    }),
   },
 });
 
@@ -1171,13 +1404,27 @@ InvokeCommand.examples = [
   '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',
+  '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 -',
 ];
 InvokeCommand.description = `Invoke an auth operation, a trigger, or a create/search action locally.
 
 This 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.
 
+Why use this command?
+
+* Fast feedback loop: Write code and run this command to verify if it works immediately
+* Step-by-step debugging: Running locally means you can use a debugger to step through your code
+* Untruncated logs: View complete logs and errors in your terminal
+
+### Authentication
+
+You can supply the authentcation data in two ways: Load from the local \`.env\` file or use the (experimental) \`--authentication-id\` flag.
+
+#### The local \`.env\` file
+
 This 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.
 
 The \`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.
@@ -1197,6 +1444,19 @@ authData_refresh_token='abcdefg'
 authData_account_name='zapier'
 \`\`\`
 
+
+#### The \`--authentication-id\` flag (EXPERIMENTAL)
+
+Setting 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.
+
+The \`--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.
+
+When \`-a -\` is specified, such as \`zapier invoke auth test -a -\`, the command will interactively prompt you to select one of your available authentications.
+
+If you know your authentication ID, you can specify it directly, such as \`zapier invoke auth test -a 123456\`.
+
+#### Testing authentication
+
 To test if the auth data is correct, run either one of these:
 
 \`\`\`
@@ -1204,7 +1464,9 @@ zapier invoke auth test   # invokes authentication.test method
 zapier invoke auth label  # invokes authentication.test and renders connection label
 \`\`\`
 
-To refresh stale auth data for OAuth2 or session auth, run \`zapier invoke auth refresh\`.
+To 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.
+
+### Invoking a trigger or an action
 
 Once 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\`:
 
@@ -1212,12 +1474,14 @@ Once you have the correct auth data, you can test an trigger, a search, or a cre
 zapier invoke trigger new_recipe
 \`\`\`
 
-To add input data, use the \`--inputData\` flag. The input data can come from the command directly, a file, or stdin. See **EXAMPLES** below.
+To 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.
 
 When 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.
 
 The \`--debug\` flag will show you the HTTP request logs and any console logs you have in your code.
 
+### Limitations
+
 The following is a non-exhaustive list of current limitations and may be supported in the future:
 
 - Hook triggers, including REST hook subscribe/unsubscribe

package/src/utils/api.js

@@ -293,6 +293,11 @@ const getVersionInfo = () => {
   });
 };
 
+const getSpecificVersionInfo = async (version) => {
+  const app = await getWritableApp();
+  return callAPI(`/apps/${app.id}/versions/${version}`);
+};
+
 // Intended to match logic of https://gitlab.com/zapier/team-developer-platform/dev-platform/-/blob/9fa28d8bacd04ebdad5937bd039c71aede4ede47/web/frontend/assets/app/entities/CliApp/CliApp.ts#L96
 const isPublished = (appStatus) => {
   const publishedStatuses = ['public', 'beta'];
@@ -363,6 +368,8 @@ const listEnv = (version) =>
 
 const listMigrations = () => listEndpoint('migrations');
 
+const listAuthentications = () => listEndpoint('authentications');
+
 // the goal of this is to call `/check` with as much info as possible
 // if the app is registered and auth is available, then we can send app id
 // otherwise, we should just send the definition and get back checks about that
@@ -500,8 +507,10 @@ module.exports = {
   getLinkedAppConfig,
   getWritableApp,
   getVersionInfo,
+  getSpecificVersionInfo,
   isPublished,
   listApps,
+  listAuthentications,
   listCanaries,
   listEndpoint,
   listEndpointMulti,

package/src/utils/local.js

@@ -2,8 +2,231 @@ const _ = require('lodash');
 const path = require('path');
 
 const { findCorePackageDir } = require('./misc');
+const { BASE_ENDPOINT } = require('../constants');
 
-const getLocalAppHandler = ({ reload = false, baseEvent = {} } = {}) => {
+/**
+ * Wraps Node's http.request() / https.request() so that all requests go via a relay URL.
+ * It decides whether to use the http or https module based on the relay URL's protocol.
+ *
+ * @param {Function} originalHttpRequest - The original http.request function.
+ * @param {Function} originalHttpsRequest - The original https.request function.
+ * @param {string} relayUrl - The base URL to which we relay. (e.g., 'http://my-relay.test')
+ * @param {Object} relayHeaders - Extra headers to add to each request sent to the relay.
+ * @returns {Function} A function with the same signature as http(s).request that relays instead.
+ *
+ * Usage:
+ *   const http = require('http');
+ *   const https = require('https');
+ *
+ *   // Replace https.request with our wrapped version:
+ *   https.request = wrapHttpRequestFuncWithRelay(
+ *     http.request,
+ *     https.request,
+ *     'https://my-relay.test',
+ *     { 'X-Relayed-By': 'MyRelayProxy' }
+ *   );
+ *
+ *   // Now, calling https.request('https://example.com/hello') will actually
+ *   // send a request to "https://my-relay.test/example.com/hello"
+ *   // with X-Relayed-By header attached.
+ */
+function wrapHttpRequestFuncWithRelay(
+  originalHttpRequest,
+  originalHttpsRequest,
+  relayUrl,
+  relayHeaders,
+) {
+  const parsedRelayUrl = new URL(relayUrl);
+
+  // Decide if the relay itself is HTTP or HTTPS
+  const isRelayHttps = parsedRelayUrl.protocol === 'https:';
+
+  // Pick which request function to use to talk to the relay
+  const relayRequestFunc = isRelayHttps
+    ? originalHttpsRequest
+    : originalHttpRequest;
+
+  /**
+   * The actual wrapped request function.
+   * Accepts the same arguments as http(s).request:
+   *    (options[, callback]) or (url[, options][, callback])
+   */
+  return function wrappedRequest(originalOptions, originalCallback) {
+    let options;
+    let callback;
+
+    // 1. Normalize arguments (string URL vs. options object)
+    if (typeof originalOptions === 'string') {
+      // Called like request(urlString, [...])
+      try {
+        const parsedOriginalUrl = new URL(originalOptions);
+
+        if (typeof originalCallback === 'object') {
+          // request(urlString, optionsObject, callback)
+          options = { ...originalCallback };
+          callback = arguments[2];
+        } else {
+          // request(urlString, callback) or request(urlString)
+          options = {};
+          callback = originalCallback;
+        }
+
+        // Merge in the URL parts if not explicitly set in options
+        options.protocol = options.protocol || parsedOriginalUrl.protocol;
+        options.hostname = options.hostname || parsedOriginalUrl.hostname;
+        options.port = options.port || parsedOriginalUrl.port;
+        options.path =
+          options.path || parsedOriginalUrl.pathname + parsedOriginalUrl.search;
+      } catch (err) {
+        // If it's not a valid absolute URL, treat it as a path
+        // or re-throw if you prefer strictness.
+        options = {};
+        callback = originalCallback;
+        options.path = originalOptions;
+      }
+    } else {
+      // Called like request(optionsObject, [callback])
+      options = { ...originalOptions };
+      callback = originalCallback;
+    }
+
+    // 2. Default method and headers
+    if (!options.method) {
+      options.method = 'GET';
+    }
+    if (!options.headers) {
+      options.headers = {};
+    }
+
+    // 3. Decide whether to relay or not
+    // If the request is being sent to the same host:port as our relay,
+    // we do NOT want to relay again. We just call the original request.
+    const targetHost = (options.hostname || options.host)
+      .replaceAll('lcurly-', '{{')
+      .replaceAll('-rcurly', '}}');
+    const targetPort = options.port ? String(options.port) : '';
+    const relayHost = parsedRelayUrl.hostname;
+    const relayPort = parsedRelayUrl.port ? String(parsedRelayUrl.port) : '';
+
+    const isAlreadyRelay =
+      targetHost === relayHost &&
+      // If no port was specified, assume default port comparison as needed
+      (targetPort === relayPort || (!targetPort && !relayPort));
+
+    if (isAlreadyRelay) {
+      // Just call the original function; do *not* re-relay
+      const originalFn =
+        options.protocol === 'https:'
+          ? originalHttpsRequest
+          : originalHttpRequest;
+      return originalFn(options, callback);
+    }
+
+    // 4. Otherwise, build the path we want to relay to
+    let finalHost = targetHost;
+    if (targetPort && targetPort !== '443') {
+      finalHost += `:${targetPort}`;
+    }
+    const combinedPath = `${parsedRelayUrl.pathname}/${finalHost}${options.path}`;
+
+    // 5. Build final options for the relay request
+    const relayedOptions = {
+      protocol: parsedRelayUrl.protocol,
+      hostname: relayHost,
+      port: relayPort,
+      path: combinedPath,
+      method: options.method,
+      headers: {
+        ...options.headers,
+        ...relayHeaders,
+      },
+    };
+
+    // 6. Make the relay request
+    const relayReq = relayRequestFunc(relayedOptions, callback);
+    return relayReq;
+  };
+}
+
+/**
+ * Wraps a fetch function so that all requests get relayed to a specified relay URL.
+ * The final relay URL includes: relayUrl + "/" + originalHost + originalPath
+ *
+ * @param {Function} fetchFunc - The original fetch function (e.g., global.fetch).
+ * @param {string} relayUrl - The base URL to which we relay. (e.g. 'https://my-relay.test')
+ * @param {Object} relayHeaders - Extra headers to add to each request sent to the relay.
+ * @returns {Function} A function with the same signature as `fetch(url, options)`.
+ *
+ * Usage:
+ *   const wrappedFetch = wrapFetchWithRelay(
+ *     fetch,
+ *     'https://my-relay.test',
+ *     { 'X-Relayed-By': 'MyRelayProxy' },
+ *   );
+ *
+ *   // Now when you do:
+ *   //   wrappedFetch('https://example.com/api/user?id=123', { method: 'POST' });
+ *   // it actually sends a request to:
+ *   //   https://my-relay.test/example.com/api/user?id=123
+ *   // with "X-Relayed-By" header included.
+ */
+function wrapFetchWithRelay(fetchFunc, relayUrl, relayHeaders) {
+  const parsedRelayUrl = new URL(relayUrl);
+
+  return async function wrappedFetch(originalUrl, originalOptions = {}) {
+    // Attempt to parse the originalUrl as an absolute URL
+    const parsedOriginalUrl = new URL(originalUrl);
+
+    // Build the portion that includes the original host (and port if present)
+    let host = parsedOriginalUrl.hostname;
+    // If there's a port that isn't 443 (for HTTPS) or 80 (for HTTP), append it
+    // (Adjust to your preferences; here we loosely check for 443 only.)
+    if (parsedOriginalUrl.port && parsedOriginalUrl.port.toString() !== '443') {
+      host += `:${parsedOriginalUrl.port}`;
+    }
+
+    const isAlreadyRelay =
+      parsedOriginalUrl.hostname === parsedRelayUrl.hostname &&
+      parsedOriginalUrl.port === parsedRelayUrl.port;
+    if (isAlreadyRelay) {
+      // Just call the original fetch function; do *not* re-relay
+      return fetchFunc(originalUrl, originalOptions);
+    }
+
+    // Combine the relay's pathname with the "host + path" from the original
+    // For example: relayUrl = http://my-relay.test
+    //   => parsedRelayUrl.pathname might be '/'
+    //   => combinedPath = '/example.com:8080/some/path'
+    const combinedPath = `${parsedRelayUrl.pathname}/${host}${parsedOriginalUrl.pathname}`;
+
+    // Merge in the search strings: the relay's own search (if any) plus the original URL's search
+    const finalUrl = `${parsedRelayUrl.origin}${combinedPath}${parsedRelayUrl.search}${parsedOriginalUrl.search}`;
+
+    // Merge the user's headers with the relayHeaders
+    const mergedHeaders = {
+      ...(originalOptions.headers || {}),
+      ...relayHeaders,
+    };
+
+    const finalOptions = {
+      ...originalOptions,
+      headers: mergedHeaders,
+    };
+
+    // Call the real fetch with our new URL and merged options
+    return fetchFunc(finalUrl, finalOptions);
+  };
+}
+
+const getLocalAppHandler = ({
+  reload = false,
+  baseEvent = {},
+  appId = null,
+  deployKey = null,
+  relayAuthenticationId = null,
+  beforeRequest = null,
+  afterResponse = null,
+} = {}) => {
   const entryPath = `${process.cwd()}/index`;
   const rootPath = path.dirname(require.resolve(entryPath));
   const corePackageDir = findCorePackageDir();
@@ -24,6 +247,41 @@ const getLocalAppHandler = ({ reload = false, baseEvent = {} } = {}) => {
     // maybe we could do require('syntax-error') in the future
     return (event, ctx, callback) => callback(err);
   }
+
+  if (beforeRequest) {
+    appRaw.beforeRequest = [...(appRaw.beforeRequest || []), ...beforeRequest];
+  }
+  if (afterResponse) {
+    appRaw.afterResponse = [...afterResponse, ...(appRaw.afterResponse || [])];
+  }
+
+  if (appId && deployKey && relayAuthenticationId) {
+    const relayUrl = `${BASE_ENDPOINT}/api/platform/cli/apps/${appId}/relay`;
+    const relayHeaders = {
+      'x-relay-authentication-id': relayAuthenticationId,
+      'x-deploy-key': deployKey,
+    };
+
+    const http = require('http');
+    const https = require('https');
+    const origHttpRequest = http.request;
+    const origHttpsRequest = https.request;
+    http.request = wrapHttpRequestFuncWithRelay(
+      origHttpRequest,
+      origHttpsRequest,
+      relayUrl,
+      relayHeaders,
+    );
+    https.request = wrapHttpRequestFuncWithRelay(
+      origHttpRequest,
+      origHttpsRequest,
+      relayUrl,
+      relayHeaders,
+    );
+
+    global.fetch = wrapFetchWithRelay(global.fetch, relayUrl, relayHeaders);
+  }
+
   const handler = zapier.createAppHandler(appRaw);
   return (event, ctx, callback) => {
     event = _.merge(
@@ -40,7 +298,13 @@ const getLocalAppHandler = ({ reload = false, baseEvent = {} } = {}) => {
 
 // Runs a local app command (./index.js) like {command: 'validate'};
 const localAppCommand = (event) => {
-  const handler = getLocalAppHandler();
+  const handler = getLocalAppHandler({
+    appId: event.appId,
+    deployKey: event.deployKey,
+    relayAuthenticationId: event.relayAuthenticationId,
+    beforeRequest: event.beforeRequest,
+    afterResponse: event.afterResponse,
+  });
   return new Promise((resolve, reject) => {
     handler(event, {}, (err, resp) => {
       if (err) {