Various doc improvements

README-source.md

@@ -93,7 +93,7 @@ cd example-app
 npm install
 ```
 
-> Note: there are plenty of templates & example apps to choose from! [View all Example Apps here.](#example-apps)
+> Note: there are plenty of templates & example apps to choose from! [View all Example Apps here.](#example-apps).
 
 You should now have a working local app. You can run several local commands to try it out.
 
@@ -224,6 +224,7 @@ If you'd like to manage your **Version**, use these commands:
 * `zapier migrate [1.0.0] [1.0.1] [100%]` - move users between versions, regardless of deployment status
 * `zapier deprecate [1.0.0] [YYYY-MM-DD]` - mark a version as deprecated, but let users continue to use it (we'll email them)
 * `zapier env 1.0.0 [KEY] [value]` - set an environment variable to some value
+* `zapier delete version [1.0.0]` - delete a version entirely. This is mostly for clearing out old test apps you used personally. It will fail if there are any users. You probably want `deprecate` instead.
 
 > Note: To see the changes that were just pushed reflected in the browser, you have to manually refresh the browser each time you push.
 
@@ -352,7 +353,7 @@ Your auth definition would look something like this:
 [insert-file:./snippets/oauth2.js]
 ```
 
-> Note - For OAuth, `authentication.oauth2Config.authorizeUrl`, `authentication.oauth2Config.getAccessToken`, and `authentication.oauth2Config.refreshAccessToken`  will have the provided fields in `bundle.inputData` instead of `bundle.authData` because `bundle.authData` will only have "previously existing" values, which will be empty the first time the Zap runs. Also note that `authentication.oauth2Config.getAccessToken` has access to the users return values in `rawRequest` and `cleanedRequest` should you need to extract other values (for example from the query string)
+> Note - For OAuth, `authentication.oauth2Config.authorizeUrl`, `authentication.oauth2Config.getAccessToken`, and `authentication.oauth2Config.refreshAccessToken`  will have the provided fields in `bundle.inputData` instead of `bundle.authData` because `bundle.authData` will only have "previously existing" values, which will be empty the first time the Zap runs. Also note that `authentication.oauth2Config.getAccessToken` has access to the users return values in `rawRequest` and `cleanedRequest` should you need to extract other values (for example from the query string).
 
 
 ## Resources
@@ -469,7 +470,7 @@ In some cases, it might be necessary to provide fields that are dynamically gene
 [insert-file:./snippets/custom-fields.js]
 ```
 
-Additionally, if there is a field that affects the generation of dynamic fields, you can set the `altersDynamicFields: true` property. This informs the Zapier UI that whenever the value of that field changes, fields need to be recomputed. An example could be a static dropdown of "dessert type" that will change whether the function that generates dynamic fields includes a field "with sprinkles."
+Additionally, if there is a field that affects the generation of dynamic fields, you can set the `altersDynamicFields: true` property. This informs the Zapier UI that whenever the value of that field changes, fields need to be recomputed. An example could be a static dropdown of "dessert type" that will change whether the function that generates dynamic fields includes a field "with sprinkles." If your field affects others, this is an important property to set.
 
 ```js
 [insert-file:./snippets/alters-dynamic-fields.js]
@@ -493,8 +494,6 @@ In the UI, users will see something like this:
 
 ![screenshot of dynamic dropdown in Zap Editor](https://cdn.zapier.com/storage/photos/dd31fa761e0cf9d0abc9b50438f95210.png)
 
-> Dynamic dropdowns are one of the few fields that automatically invalidate Zapier's field cache, so it is not necessary to set `altersDynamicFields` to true for these fields.
-
 ### Search-Powered Fields
 
 For fields that take id of another object to create a relationship between the two (EG: a project id for a ticket), you can specify the `search` property on the field to indicate that Zapier needs to prompt the user to setup a Search step to populate the value for this field. Similar to dynamic dropdowns, the value for this property is a dot-separated concatenation of a search's key and the field to use for the value.
@@ -640,7 +639,7 @@ This object holds the user's auth details and the data for the API requests.
 | limit | `-1` | the number of items to fetch. `-1` indicates there's no limit (which will almost always be the case) |
 | page | `0` | used in [paging](#paging) to uniquely identify which page of results should be returned |
 
-> `bundle.meta.zap.id` is only available in the `performSubscribe` and `performUnsubscribe` methods
+> `bundle.meta.zap.id` is only available in the `performSubscribe` and `performUnsubscribe` methods.
 
 The user's Zap ID is available during the [subscribe and unsubscribe](https://zapier.github.io/zapier-platform-schema/build/schema.html#basichookoperationschema) methods.
 
@@ -669,7 +668,7 @@ module.exports = {
 ```
 
 ### `bundle.rawRequest`
-> `bundle.rawRequest` is only available in the `perform` for web hooks and `getAccessToken` for oauth authentication methods
+> `bundle.rawRequest` is only available in the `perform` for web hooks and `getAccessToken` for oauth authentication methods.
 
 `bundle.rawRequest` holds raw information about the HTTP request that triggered the `perform` method or that represents the users browser request that triggered the `getAccessToken` call:
 
@@ -687,7 +686,7 @@ module.exports = {
 
 
 ### `bundle.cleanedRequest`
-> `bundle.cleanedRequest` is only available in the `perform` for web hooks and `getAccessToken` for oauth authentication methods
+> `bundle.cleanedRequest` is only available in the `perform` for webhooks and `getAccessToken` for oauth authentication methods.
 
 `bundle.cleanedRequest` will return a formatted and parsed version of the request. Some or all of the following will be available:
 
@@ -707,6 +706,21 @@ module.exports = {
 }
 ```
 
+### `bundle.targetUrl`
+
+> `bundle.targetUrl` is only available in the `performSubscribe` and `performUnsubscribe` methods for webhooks.
+
+This the URL to which you should send hook data. It'll look something like `https://hooks.zapier.com/1234/abcd`. We provide it so you can make a POST request to your server.Your server should store this URL and use is as a destination when there's new data to report.
+
+Read more in the [REST hook example](https://github.com/zapier/zapier-platform-example-app-rest-hooks/blob/master/triggers/recipe.js).
+
+### `bundle.subscribeData`
+
+> `bundle.subscribeData` is only available in the `performUnsubscribe` method for webhooks.
+
+This is an object that contains the data you returned from the `performSubscribe` function. It should contain whatever information you need send a `DELETE` request to your server to stop sending webhooks to Zapier.
+
+Read more in the [REST hook example](https://github.com/zapier/zapier-platform-example-app-rest-hooks/blob/master/triggers/recipe.js).
 
 ## Environment
 
@@ -776,7 +790,7 @@ For example, you can access the `process.env` in your perform functions and in t
 [insert-file:./snippets/process-env.js]
 ```
 
-> Note! Be sure to lazily access your environment variables - see [When to use placeholders or curlies?](#when-to-use-placeholders-or-curlies)
+> Note! Be sure to lazily access your environment variables - see [When to use placeholders or curlies?](#when-to-use-placeholders-or-curlies).
 
 
 ## Making HTTP Requests
@@ -808,7 +822,7 @@ This features:
 [insert-file:./snippets/shorthand-request.js]
 ```
 
-In the url above, `{{bundle.authData.subdomain}}` is automatically replaced with the live value from the bundle. If the call returns a non 2xx return code, an error is automatically raised. The response body is automatically parsed as JSON and returned.
+In the URL above, `{{bundle.authData.subdomain}}` is automatically replaced with the live value from the bundle. If the call returns a non 2xx return code, an error is automatically raised. The response body is automatically parsed as JSON and returned.
 
 An error will be raised if the response is not valid JSON, so _do not use shorthand HTTP requests with non-JSON responses_.
 
@@ -1344,7 +1358,7 @@ Yes, though there are caveats. Your entire function only gets 30 seconds to run.
 [insert-file:./snippets/paging-poll.js]
 ```
 
-If you need to do more requests conditionally based on the results of an HTTP call (such as the "next url" param or similar value), using `async/await` (as shown in the example below) is a good way to go. If you go this route, only page as far as you need to. Keep an eye on the polling [guidelines](https://zapier.com/developer/documentation/v2/deduplication/), namely the part about only iterating until you hit items that have probably been seen in a previous poll.
+If you need to do more requests conditionally based on the results of an HTTP call (such as the "next URL" param or similar value), using `async/await` (as shown in the example below) is a good way to go. If you go this route, only page as far as you need to. Keep an eye on the polling [guidelines](https://zapier.com/developer/documentation/v2/deduplication/), namely the part about only iterating until you hit items that have probably been seen in a previous poll.
 
 ```js
 [insert-file:./snippets/async-polling.js]

README.md

@@ -71,6 +71,8 @@ Zapier is a platform for creating integrations and workflows. This CLI is your g
   * [`bundle.meta`](#bundlemeta)
   * [`bundle.rawRequest`](#bundlerawrequest)
   * [`bundle.cleanedRequest`](#bundlecleanedrequest)
+  * [`bundle.targetUrl`](#bundletargeturl)
+  * [`bundle.subscribeData`](#bundlesubscribedata)
 - [Environment](#environment)
   * [Defining Environment Variables](#defining-environment-variables)
   * [Accessing Environment Variables](#accessing-environment-variables)
@@ -354,6 +356,7 @@ If you'd like to manage your **Version**, use these commands:
 * `zapier migrate [1.0.0] [1.0.1] [100%]` - move users between versions, regardless of deployment status
 * `zapier deprecate [1.0.0] [YYYY-MM-DD]` - mark a version as deprecated, but let users continue to use it (we'll email them)
 * `zapier env 1.0.0 [KEY] [value]` - set an environment variable to some value
+* `zapier delete version [1.0.0]` - delete a version entirely. This is mostly for clearing out old test apps you used personally. It will fail if there are any users. You probably want `deprecate` instead.
 
 > Note: To see the changes that were just pushed reflected in the browser, you have to manually refresh the browser each time you push.
 
@@ -1298,7 +1301,7 @@ module.exports = {
 
 
 ### `bundle.cleanedRequest`
-> `bundle.cleanedRequest` is only available in the `perform` for web hooks and `getAccessToken` for oauth authentication methods
+> `bundle.cleanedRequest` is only available in the `perform` for webhooks and `getAccessToken` for oauth authentication methods
 
 `bundle.cleanedRequest` will return a formatted and parsed version of the request. Some or all of the following will be available:
 
@@ -1318,6 +1321,21 @@ module.exports = {
 }
 ```
 
+### `bundle.targetUrl`
+
+> `bundle.targetUrl` is only available in the `performSubscribe` and `performUnsubscribe` methods for webhooks
+
+This the url to which you should send hook data. It'll look something like `https://hooks.zapier.com/1234/abcd`. We provide it so you can make some sort of POST request to your server and store this as a destination for new info.
+
+Read more in the [REST hook example](https://github.com/zapier/zapier-platform-example-app-rest-hooks/blob/master/triggers/recipe.js).
+
+### `bundle.subscribeData`
+
+> `bundle.subscribeData` is only available in the `performUnsubscribe` method for webhooks
+
+This is an object that contains the data you returned from the `performSubscribe` function. It should contain whatever information you need send a `DELETE` request to your server to stop sending webhooks to Zapier.
+
+Read more in the [REST hook example](https://github.com/zapier/zapier-platform-example-app-rest-hooks/blob/master/triggers/recipe.js).
 
 ## Environment
 

docs/cli.html

@@ -1079,7 +1079,9 @@ <h2 id="push">push</h2>
 <li>Go to 1 and repeat.</li>
 </ol><blockquote>
 <p>Note: this is always a safe operation as live/production apps are protected from pushes. You must use <code>zapier promote</code> or <code>zapier migrate</code> to impact live users.</p>
-</blockquote><p>If you have not yet registered your app, this command will prompt you for your app title and register the app.</p>
+</blockquote><blockquote>
+<p>Note: this will overwrite the version specified in your <code>package.json</code>. If you want to push to a new version, increment the &quot;version&quot; key.</p>
+</blockquote><p>If you have not yet registered your app, this command will prompt you for your app title and to register the app.</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height  docs-code">
       <pre><code class="lang-bash">$ zapier push

docs/cli.md

@@ -723,7 +723,9 @@ A shortcut for `zapier build && zapier upload` - this is our recommended way to
 
 > Note: this is always a safe operation as live/production apps are protected from pushes. You must use `zapier promote` or `zapier migrate` to impact live users.
 
-If you have not yet registered your app, this command will prompt you for your app title and register the app.
+> Note: this will overwrite the version specified in your `package.json`. If you want to push to a new version, increment the "version" key.
+
+If you have not yet registered your app, this command will prompt you for your app title and to register the app.
 
 ```bash
 $ zapier push

docs/index.html

@@ -310,6 +310,8 @@ <h2 class="docs-header__platform-title">Developer Platform</h2>
 <li><a href="#bundlemeta"><code>bundle.meta</code></a></li>
 <li><a href="#bundlerawrequest"><code>bundle.rawRequest</code></a></li>
 <li><a href="#bundlecleanedrequest"><code>bundle.cleanedRequest</code></a></li>
+<li><a href="#bundletargeturl"><code>bundle.targetUrl</code></a></li>
+<li><a href="#bundlesubscribedata"><code>bundle.subscribeData</code></a></li>
 </ul>
 </li>
 <li><a href="#environment">Environment</a><ul>
@@ -501,6 +503,8 @@ <h2 id="table-of-contents">Table of Contents</h2>
 <li><a href="#bundlemeta"><code>bundle.meta</code></a></li>
 <li><a href="#bundlerawrequest"><code>bundle.rawRequest</code></a></li>
 <li><a href="#bundlecleanedrequest"><code>bundle.cleanedRequest</code></a></li>
+<li><a href="#bundletargeturl"><code>bundle.targetUrl</code></a></li>
+<li><a href="#bundlesubscribedata"><code>bundle.subscribeData</code></a></li>
 </ul>
 </li>
 <li><a href="#environment">Environment</a><ul>
@@ -995,6 +999,7 @@ <h2 id="deploying-an-app-version">Deploying an App Version</h2>
 <li><code>zapier migrate [1.0.0] [1.0.1] [100%]</code> - move users between versions, regardless of deployment status</li>
 <li><code>zapier deprecate [1.0.0] [YYYY-MM-DD]</code> - mark a version as deprecated, but let users continue to use it (we&apos;ll email them)</li>
 <li><code>zapier env 1.0.0 [KEY] [value]</code> - set an environment variable to some value</li>
+<li><code>zapier delete version [1.0.0]</code> - delete a version entirely. This is mostly for clearing out old test apps you used personally. It will fail if there are any users. You probably want <code>deprecate</code> instead.</li>
 </ul><blockquote>
 <p>Note: To see the changes that were just pushed reflected in the browser, you have to manually refresh the browser each time you push.</p>
 </blockquote>
@@ -2540,7 +2545,7 @@ <h3 id="bundlecleanedrequest"><code>bundle.cleanedRequest</code></h3>
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
       <blockquote>
-<p><code>bundle.cleanedRequest</code> is only available in the <code>perform</code> for web hooks and <code>getAccessToken</code> for oauth authentication methods</p>
+<p><code>bundle.cleanedRequest</code> is only available in the <code>perform</code> for webhooks and <code>getAccessToken</code> for oauth authentication methods</p>
 </blockquote><p><code>bundle.cleanedRequest</code> will return a formatted and parsed version of the request. Some or all of the following will be available:</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height  docs-code">
@@ -2561,6 +2566,46 @@ <h3 id="bundlecleanedrequest"><code>bundle.cleanedRequest</code></h3>
     </div>
   </div>
 </div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <h3 id="bundletargeturl"><code>bundle.targetUrl</code></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">
+      <blockquote>
+<p><code>bundle.targetUrl</code> is only available in the <code>performSubscribe</code> and <code>performUnsubscribe</code> methods for webhooks</p>
+</blockquote><p>This the url to which you should send hook data. It&apos;ll look something like <code>https://hooks.zapier.com/1234/abcd</code>. We provide it so you can make some sort of POST request to your server and store this as a destination for new info.</p><p>Read more in the <a href="https://github.com/zapier/zapier-platform-example-app-rest-hooks/blob/master/triggers/recipe.js">REST hook example</a>.</p>
+    </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="bundlesubscribedata"><code>bundle.subscribeData</code></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">
+      <blockquote>
+<p><code>bundle.subscribeData</code> is only available in the <code>performUnsubscribe</code> method for webhooks</p>
+</blockquote><p>This is an object that contains the data you returned from the <code>performSubscribe</code> function. It should contain whatever information you need send a <code>DELETE</code> request to your server to stop sending webhooks to Zapier.</p><p>Read more in the <a href="https://github.com/zapier/zapier-platform-example-app-rest-hooks/blob/master/triggers/recipe.js">REST hook example</a>.</p>
+    </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">
       <h2 id="environment">Environment</h2>

src/commands/push.js

@@ -37,7 +37,9 @@ A shortcut for \`zapier build && zapier upload\` - this is our recommended way t
 
 > Note: this is always a safe operation as live/production apps are protected from pushes. You must use \`zapier promote\` or \`zapier migrate\` to impact live users.
 
-If you have not yet registered your app, this command will prompt you for your app title and register the app.
+> Note: this command will create (or overwrite) an AppVersion that matches the ones listed in your \`package.json\`. If you want to push to a new version, increment the "version" key in \`package.json\`.
+
+If you have not yet registered your app, this command will prompt you for your app title and to register the app.
 
 ${'```'}bash
 $ zapier push