Merge pull request #872 from zapier/PDE-5319-invoke-auth-start

PDE-5319 feat(cli): `invoke auth start` subcommand

.github/workflows/ci.yaml

@@ -29,7 +29,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [16.x, 18.x]
+        node-version: [18.x, 20.x]
 
     steps:
       - uses: actions/checkout@v3
@@ -83,7 +83,7 @@ jobs:
           - ubuntu-latest
           # TODO: Fix tests on Windows
           # - windows-latest
-        node-version: [16.x, 18.x]
+        node-version: [18.x, 20.x]
 
     steps:
       - uses: actions/checkout@v3
@@ -108,7 +108,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [16.x, 18.x]
+        node-version: [18.x, 20.x]
 
     steps:
       - uses: actions/checkout@v3
@@ -142,7 +142,7 @@ jobs:
           - ubuntu-latest
           # TODO: Fix tests on Windows
           # - windows-latest
-        node-version: [16.x, 18.x]
+        node-version: [18.x, 20.x]
 
     steps:
       - uses: actions/checkout@v3

docs/cli.html

@@ -754,13 +754,24 @@ <h2 id="invoke">invoke</h2>
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
       <blockquote>
 <p>Invoke an auth operation, a trigger, or a create/search action locally.</p>
-</blockquote><p><strong>Usage</strong>: <code>zapier invoke [ACTIONTYPE] [ACTIONKEY]</code></p><p>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.</p><p>This command loads <code>authData</code> from the <code>.env</code> file in the current directory. Create a <code>.env</code> file with the necessary auth data before running this command. Each line in <code>.env</code> should be in the format <code>authData_FIELD_KEY=VALUE</code>. For example, an OAuth2 integration might have a <code>.env</code> file like this:</p>
+</blockquote><p><strong>Usage</strong>: <code>zapier invoke [ACTIONTYPE] [ACTIONKEY]</code></p><p>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.</p><p>This command loads environment variables and <code>authData</code> from the <code>.env</code> file in the current directory. If you don&apos;t have an <code>.env</code> file yet, you can use the <code>zapier invoke auth start</code> command to help you initialize it, or you can manually create it.</p><p>The <code>zapier invoke auth start</code> subcommand will prompt you for the necessary auth fields and save them to the <code>.env</code> file.</p><p>Each line in the <code>.env</code> file should follow one of these formats:</p><ul>
+<li><p><code>VAR_NAME=VALUE</code> for environment variables</p>
+</li>
+<li><p><code>authData_FIELD_KEY=VALUE</code> for auth data fields</p>
+</li>
+</ul><p>For example, a <code>.env</code> file for an OAuth2 integration might look like this:</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height  docs-code">
       <pre><code>
-authData_access_token=1234567890
+CLIENT_ID=&apos;your_client_id&apos;
+
+CLIENT_SECRET=&apos;your_client_secret&apos;
 
-authData_other_auth_field=abcdef
+authData_access_token=&apos;1234567890&apos;
+
+authData_refresh_token=&apos;abcdefg&apos;
+
+authData_account_name=&apos;zapier&apos;
 
 </code></pre>
     </div>
@@ -782,7 +793,7 @@ <h2 id="invoke">invoke</h2>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p>Then you can test an trigger, a search, or a create action. For example, this is how you invoke a trigger with key <code>new_recipe</code>:</p>
+      <p>Once you have the correct auth data, you can test an trigger, a search, or a create action. For example, here&apos;s how you invoke a trigger with the key <code>new_recipe</code>:</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height  docs-code">
       <pre><code>
@@ -794,9 +805,7 @@ <h2 id="invoke">invoke</h2>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p>To add input data, use the <code>--inputData</code> flag. The input data can come from the command directly, a file, or stdin. See <strong>EXAMPLES</strong> below.</p><p>The following are current limitations and may be supported in the future:</p><ul>
-<li><p><code>zapier invoke auth start</code> to help you initialize the auth data in <code>.env</code></p>
-</li>
+      <p>To add input data, use the <code>--inputData</code> flag. The input data can come from the command directly, a file, or stdin. See <strong>EXAMPLES</strong> below.</p><p>When you miss any command arguments, such as ACTIONTYPE or ACTIONKEY, the command will prompt you interactively. If you don&apos;t want to get interactive prompts, use the <code>--non-interactive</code> flag.</p><p>The <code>--debug</code> flag will show you the HTTP request logs and any console logs you have in your code.</p><p>The following is a non-exhaustive list of current limitations and may be supported in the future:</p><ul>
 <li><p><code>zapier invoke auth refresh</code> to refresh the auth data in <code>.env</code></p>
 </li>
 <li><p>Hook triggers, including REST hook subscribe/unsubscribe</p>
@@ -813,21 +822,33 @@ <h2 id="invoke">invoke</h2>
 </li>
 <li><p>Buffered create actions</p>
 </li>
+<li><p>Search-or-create actions</p>
+</li>
+<li><p>Search-powered fields</p>
+</li>
+<li><p>Field choices</p>
+</li>
+<li><p>autoRefresh for OAuth2 and session auth</p>
+</li>
 </ul><p><strong>Arguments</strong></p><ul>
 <li><code>actionType</code> | The action type you want to invoke.</li>
-<li><code>actionKey</code> | The trigger/action key you want to invoke. If ACTIONTYPE is &quot;auth&quot;, this can be &quot;test&quot; or &quot;label&quot;.</li>
+<li><code>actionKey</code> | The trigger/action key you want to invoke. If ACTIONTYPE is &quot;auth&quot;, this can be &quot;label&quot;, &quot;start&quot;, or &quot;test&quot;.</li>
 </ul><p><strong>Flags</strong></p><ul>
 <li><code>-i, --inputData</code> | The input data to pass to the action. Must be a JSON-encoded object. The data can be passed from the command directly like &apos;{&quot;key&quot;: &quot;value&quot;}&apos;, read from a file like @file.json, or read from stdin like @-.</li>
-<li><code>--isLoadingSample</code> | Set bundle.meta.isLoadingSample to true. When true in production, this run is initiated by the user in the Zap editor trying to pull a sample.</li>
 <li><code>--isFillingDynamicDropdown</code> | Set bundle.meta.isFillingDynamicDropdown to true. Only makes sense for a polling trigger. When true in production, this poll is being used to populate a dynamic dropdown.</li>
+<li><code>--isLoadingSample</code> | Set bundle.meta.isLoadingSample to true. When true in production, this run is initiated by the user in the Zap editor trying to pull a sample.</li>
 <li><code>--isPopulatingDedupe</code> | Set bundle.meta.isPopulatingDedupe to true. Only makes sense for a polling trigger. When true in production, the results of this poll will be used initialize the deduplication list rather than trigger a Zap. This happens when a user enables a Zap.</li>
 <li><code>--limit</code> | Set bundle.meta.limit. Only makes sense for a trigger. When used in production, this indicates the number of items you should fetch. -1 means no limit.  Defaults to <code>-1</code>.</li>
 <li><code>-p, --page</code> | Set bundle.meta.page. Only makes sense for a trigger. When used in production, this indicates which page of items you should fetch. First page is 0.</li>
-<li><code>-z, --timezone</code> | Set the default timezone for datetime fields. If not set, defaults to America/Chicago, which matches Zapier production behavior. Find the list timezone names at <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">https://en.wikipedia.org/wiki/List_of_tz_database_time_zones</a>.  Defaults to <code>America/Chicago</code>.</li>
+<li><code>--non-interactive</code> | Do not show interactive prompts.</li>
+<li><code>-z, --timezone</code> | Set the default timezone for datetime field interpretation. If not set, defaults to America/Chicago, which matches Zapier production behavior. Find the list timezone names at <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">https://en.wikipedia.org/wiki/List_of_tz_database_time_zones</a>.  Defaults to <code>America/Chicago</code>.</li>
+<li><code>--redirect-uri</code> | The redirect URI that will be passed to the OAuth2 authorization URL. Usually this should match the one configured in your server&apos;s OAuth2 application settings. A local HTTP server will be started to listen for the OAuth2 callback. If your server requires a non-localhost or HTTPS address for the redirect URI, you can set up port forwarding to route the non-localhost or HTTPS address to localhost.  Defaults to <code>http://localhost:9000</code>.</li>
 <li><code>-d, --debug</code> | Show extra debugging output.</li>
 </ul><p><strong>Examples</strong></p><ul>
 <li><code>zapier invoke</code></li>
+<li><code>zapier invoke auth start</code></li>
 <li><code>zapier invoke auth test</code></li>
+<li><code>zapier invoke auth label</code></li>
 <li><code>zapier invoke trigger new_recipe</code></li>
 <li><code>zapier invoke create add_recipe --inputData &apos;{&quot;title&quot;: &quot;Pancakes&quot;}&apos;</code></li>
 <li><code>zapier invoke search find_recipe -i @file.json</code></li>

docs/cli.md

@@ -318,13 +318,29 @@ This command also checks the current directory for a linked integration.
 
 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.
 
-This command loads `authData` from the `.env` file in the current directory. Create a `.env` file with the necessary auth data before running this command. Each line in `.env` should be in the format `authData_FIELD_KEY=VALUE`. For example, an OAuth2 integration might have a `.env` file like this:
+This command loads environment variables and `authData` from the `.env` file in the current directory. If you don't have an `.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.
+
+Each line in the `.env` file should follow one of these formats:
+
+* `VAR_NAME=VALUE` for environment variables
+
+* `authData_FIELD_KEY=VALUE` for auth data fields
+
+For example, a `.env` file for an OAuth2 integration might look like this:
 
 ```
 
-authData_access_token=1234567890
+CLIENT_ID='your_client_id'
+
+CLIENT_SECRET='your_client_secret'
+
+authData_access_token='1234567890'
+
+authData_refresh_token='abcdefg'
 
-authData_other_auth_field=abcdef
+authData_account_name='zapier'
 
 ```
 
@@ -338,7 +354,7 @@ zapier invoke auth label  # invokes authentication.test and renders connection l
 
 ```
 
-Then you can test an trigger, a search, or a create action. For example, this is how you invoke a trigger with key `new_recipe`:
+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`:
 
 ```
 
@@ -348,9 +364,11 @@ 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.
 
-The following are current limitations and may be supported in the future:
+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.
 
-- `zapier invoke auth start` to help you initialize the auth data in `.env`
+The `--debug` flag will show you the HTTP request logs and any console logs you have in your code.
+
+The following is a non-exhaustive list of current limitations and may be supported in the future:
 
 - `zapier invoke auth refresh` to refresh the auth data in `.env`
 
@@ -368,23 +386,35 @@ The following are current limitations and may be supported in the future:
 
 - Buffered create actions
 
+- Search-or-create actions
+
+- Search-powered fields
+
+- Field choices
+
+- autoRefresh for OAuth2 and session auth
+
 **Arguments**
 * `actionType` | The action type you want to invoke.
-* `actionKey` | The trigger/action key you want to invoke. If ACTIONTYPE is "auth", this can be "test" or "label".
+* `actionKey` | The trigger/action key you want to invoke. If ACTIONTYPE is "auth", this can be "label", "start", or "test".
 
 **Flags**
 * `-i, --inputData` | The input data to pass to the action. Must be a JSON-encoded object. The data can be passed from the command directly like '{"key": "value"}', read from a file like @file.json, or read from stdin like @-.
-* `--isLoadingSample` | Set bundle.meta.isLoadingSample to true. When true in production, this run is initiated by the user in the Zap editor trying to pull a sample.
 * `--isFillingDynamicDropdown` | Set bundle.meta.isFillingDynamicDropdown to true. Only makes sense for a polling trigger. When true in production, this poll is being used to populate a dynamic dropdown.
+* `--isLoadingSample` | Set bundle.meta.isLoadingSample to true. When true in production, this run is initiated by the user in the Zap editor trying to pull a sample.
 * `--isPopulatingDedupe` | Set bundle.meta.isPopulatingDedupe to true. Only makes sense for a polling trigger. When true in production, the results of this poll will be used initialize the deduplication list rather than trigger a Zap. This happens when a user enables a Zap.
 * `--limit` | Set bundle.meta.limit. Only makes sense for a trigger. When used in production, this indicates the number of items you should fetch. -1 means no limit.  Defaults to `-1`.
 * `-p, --page` | Set bundle.meta.page. Only makes sense for a trigger. When used in production, this indicates which page of items you should fetch. First page is 0.
-* `-z, --timezone` | Set the default timezone for datetime fields. If not set, defaults to America/Chicago, which matches Zapier production behavior. Find the list timezone names at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.  Defaults to `America/Chicago`.
+* `--non-interactive` | Do not show interactive prompts.
+* `-z, --timezone` | Set the default timezone for datetime field interpretation. If not set, defaults to America/Chicago, which matches Zapier production behavior. Find the list timezone names at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.  Defaults to `America/Chicago`.
+* `--redirect-uri` | The redirect URI that will be passed to the OAuth2 authorization URL. Usually this should match the one configured in your server's OAuth2 application settings. A local HTTP server will be started to listen for the OAuth2 callback. If your server requires a non-localhost or HTTPS address for the redirect URI, you can set up port forwarding to route the non-localhost or HTTPS address to localhost.  Defaults to `http://localhost:9000`.
 * `-d, --debug` | Show extra debugging output.
 
 **Examples**
 * `zapier invoke`
+* `zapier invoke auth start`
 * `zapier invoke auth test`
+* `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`

docs/index.html

@@ -366,6 +366,7 @@
 </ul>
 </li>
 <li><a href="#testing">Testing</a><ul>
+<li><a href="#using-zapier-invoke-command">Using <code>zapier invoke</code> Command</a></li>
 <li><a href="#writing-unit-tests">Writing Unit Tests</a></li>
 <li><a href="#using-the-z-object-in-tests">Using the <code>z</code> Object in Tests</a></li>
 <li><a href="#mocking-requests">Mocking Requests</a></li>
@@ -590,6 +591,7 @@ <h2 id="table-of-contents">Table of Contents</h2>
 </ul>
 </li>
 <li><a href="#testing">Testing</a><ul>
+<li><a href="#using-zapier-invoke-command">Using <code>zapier invoke</code> Command</a></li>
 <li><a href="#writing-unit-tests">Writing Unit Tests</a></li>
 <li><a href="#using-the-z-object-in-tests">Using the <code>z</code> Object in Tests</a></li>
 <li><a href="#mocking-requests">Mocking Requests</a></li>
@@ -5078,14 +5080,48 @@ <h2 id="testing">Testing</h2>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p>You can write unit tests for your Zapier integration that run locally, outside of the Zapier editor.
-You can run these tests in a CI tool like <a href="https://travis-ci.com/">Travis</a>.</p>
+      <p>There are several ways to test your Zapier integration:</p><ul>
+<li>You can use the <code>zapier invoke</code> command to invoke a trigger, search, create, or an auth operation locally.</li>
+<li>You can write unit tests for your Zapier integration that run locally, outside of the Zapier editor.</li>
+<li>You can run these tests in a CI tool like <a href="https://travis-ci.com/">Travis</a>.</li>
+</ul>
+    </div>
+    <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
+
+    </div>
+  </div>
+</div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <h3 id="using-zapier-invoke-command">Using <code>zapier invoke</code> Command</h3>
     </div>
     <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
 
     </div>
   </div>
 </div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <p><em>Added in v15.17.0.</em></p><p>The <code>zapier invoke &lt;ACTION_TYPE&gt; &lt;ACTION_KEY&gt;</code> CLI command emulates how the Zapier production environment would invoke your app. Since it runs code locally, it&apos;s a fast way to debug and test interactively without needing to deploy the code to Zapier.</p><p>Its general execution flow invovles calling <code>operation.inputFields</code> of an action, resolving the input data to the expected types, and then calling the <code>operation.perform</code> method.</p><p><code>zapier invoke --help</code> should be self-explanatory, but here&apos;s a quick rundown:</p>
+    </div>
+    <div class="col-md-7 col-sm-12 col-height  docs-code">
+      <pre><code class="lang-bash"><span class="hljs-comment"># Intialize auth data in .env file</span>
+zapier invoke auth start
+
+<span class="hljs-comment"># Test your auth data in .env</span>
+zapier invoke auth <span class="hljs-built_in">test</span>
+zapier invoke auth label
+
+<span class="hljs-comment"># Invoke a polling trigger</span>
+zapier invoke trigger new_recipe
+
+<span class="hljs-comment"># Invoke a create action</span>
+zapier invoke create add_recipe --inputData <span class="hljs-string">&apos;{&quot;name&quot;: &quot;Pancakes&quot;}&apos;</span>
+zapier invoke create add_recipe --inputData @file.json
+</code></pre>
+    </div>
+  </div>
+</div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
       <h3 id="writing-unit-tests">Writing Unit Tests</h3>