From 32e526e70615256bc510b266fd3a87d091833a16 Mon Sep 17 00:00:00 2001 From: David Brownman Date: Wed, 31 Oct 2018 19:21:07 -0400 Subject: [PATCH 1/3] add various docs --- README-source.md | 18 +++++++++++++++++- src/commands/push.js | 4 +++- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/README-source.md b/README-source.md index c5222cd..0c9dbb1 100644 --- a/README-source.md +++ b/README-source.md @@ -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. @@ -687,7 +688,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 +708,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 diff --git a/src/commands/push.js b/src/commands/push.js index ea1b7a6..b55a554 100644 --- a/src/commands/push.js +++ b/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 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 From d3bde2fa932747b314ec94cd845e6ccfb31ea18f Mon Sep 17 00:00:00 2001 From: David Brownman Date: Wed, 31 Oct 2018 19:32:22 -0400 Subject: [PATCH 2/3] clarify usage around altersDynamicFields --- README-source.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README-source.md b/README-source.md index 0c9dbb1..796eb2c 100644 --- a/README-source.md +++ b/README-source.md @@ -470,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] @@ -494,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. From fa2bfb3b70aba3405aeaf73c6de6d09a6179fc6c Mon Sep 17 00:00:00 2001 From: David Brownman Date: Thu, 1 Nov 2018 12:32:56 -0400 Subject: [PATCH 3/3] doc edits --- README-source.md | 22 ++++++++++----------- README.md | 20 ++++++++++++++++++- docs/cli.html | 4 +++- docs/cli.md | 4 +++- docs/index.html | 47 +++++++++++++++++++++++++++++++++++++++++++- src/commands/push.js | 2 +- 6 files changed, 83 insertions(+), 16 deletions(-) diff --git a/README-source.md b/README-source.md index 796eb2c..1d05a21 100644 --- a/README-source.md +++ b/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. @@ -353,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 @@ -639,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. @@ -668,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: @@ -686,7 +686,7 @@ module.exports = { ### `bundle.cleanedRequest` -> `bundle.cleanedRequest` is only available in the `perform` for webhooks 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: @@ -708,15 +708,15 @@ module.exports = { ### `bundle.targetUrl` -> `bundle.targetUrl` is only available in the `performSubscribe` and `performUnsubscribe` methods for webhooks +> `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. +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 +> `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. @@ -790,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 @@ -822,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_. @@ -1358,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] diff --git a/README.md b/README.md index 5581803..4b94b1f 100644 --- a/README.md +++ b/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 diff --git a/docs/cli.html b/docs/cli.html index 9d2469a..2eaab58 100644 --- a/docs/cli.html +++ b/docs/cli.html @@ -1079,7 +1079,9 @@

push

  • Go to 1 and repeat.

    • 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.

    $ zapier push
diff --git a/docs/cli.md b/docs/cli.md
index ebd60f4..8a1d01d 100644
--- a/docs/cli.md
+++ b/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
diff --git a/docs/index.html b/docs/index.html
index 9e11ef0..923bc4f 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -310,6 +310,8 @@ 
    Developer Platform
    
 
  • bundle.meta
    • 
 
  • bundle.rawRequest
    • 
 
  • bundle.cleanedRequest
    • 
+
  • bundle.targetUrl
    • 
+
  • bundle.subscribeData
    • 
 
 
 
  • Environment
 
    • 
 
  • Environment
      
@@ -995,6 +999,7 @@ 
      Deploying an App Version
      
 
    • 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.
    
 
    
@@ -2540,7 +2545,7 @@ 
    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:
    
     
    
     
    
@@ -2561,6 +2566,46 @@ 
    bundle.cleanedRequest
    • +
    +
    +

    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.

    +
    +
    + +
    +
    +
    +
    +
    +

    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.

    +
    +
    + +
    +
    +

    Environment

    diff --git a/src/commands/push.js b/src/commands/push.js index b55a554..4fb7017 100644 --- a/src/commands/push.js +++ b/src/commands/push.js @@ -37,7 +37,7 @@ 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. -> Note: this will overwrite the version specified in your \`package.json\`. If you want to push to a new version, increment the "version" key. +> 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.