From 7abb3237e59c8614a03736b3e8b110f3db38789e Mon Sep 17 00:00:00 2001
From: kola-er <kola.erinoso@zapier.com>
Date: Thu, 5 Oct 2023 16:30:56 +0100
Subject: [PATCH] PDE-4295 Add docs for throttle configuration

---
 docs/index.html                               | 63 +++++++++++++++++++
 packages/cli/README-source.md                 | 23 +++++++
 packages/cli/README.md                        | 57 +++++++++++++++++
 packages/cli/docs/index.html                  | 63 +++++++++++++++++++
 .../cli/snippets/throttle-configuration.js    | 33 ++++++++++
 5 files changed, 239 insertions(+)
 create mode 100644 packages/cli/snippets/throttle-configuration.js

diff --git a/docs/index.html b/docs/index.html
index fba7d925f..91f742f33 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -317,6 +317,7 @@
 <li><a href="#accessing-environment-variables">Accessing Environment Variables</a></li>
 </ul>
 </li>
+<li><a href="#adding-throttle-configuration">Adding Throttle Configuration</a></li>
 <li><a href="#making-http-requests">Making HTTP Requests</a><ul>
 <li><a href="#shorthand-http-requests">Shorthand HTTP Requests</a></li>
 <li><a href="#manual-http-requests">Manual HTTP Requests</a><ul>
@@ -528,6 +529,7 @@ <h2 id="table-of-contents">Table of Contents</h2>
 <li><a href="#accessing-environment-variables">Accessing Environment Variables</a></li>
 </ul>
 </li>
+<li><a href="#adding-throttle-configuration">Adding Throttle Configuration</a></li>
 <li><a href="#making-http-requests">Making HTTP Requests</a><ul>
 <li><a href="#shorthand-http-requests">Shorthand HTTP Requests</a></li>
 <li><a href="#manual-http-requests">Manual HTTP Requests</a><ul>
@@ -3640,6 +3642,67 @@ <h3 id="accessing-environment-variables">Accessing Environment Variables</h3>
     </div>
   </div>
 </div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <h2 id="adding-throttle-configuration">Adding Throttle Configuration</h2>
+    </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.4.0.</em></p><p>When a throttle configuration is set for an action, Zapier uses it to apply throttling when the limit for the window timeframe is exceeded. It can be set at the root level and/or on an action. When set at the root level, it is the default throttle configuration used on each action of the integration. And when set in an action&apos;s operation object, the root-level default is overwritten for that action only.</p><p>To throttle an action, you need to set a <code>throttle</code> object with the following variables:</p><ol>
+<li><code>window [integer]</code>: The timeframe, in seconds, within which the system tracks the number of invocations for an action. The number of invocations begins at zero at the start of each window. It is an integer.</li>
+<li><code>limit [integer]</code>: The maximum number of invocations for an action, allowed within the timeframe window. It is an integer.</li>
+<li><code>scope [arrary]</code>: The granularity to throttle by. You can set the scope to one or more of the following options;<ul>
+<li>&apos;user&apos; - Throttles based on user ids.</li>
+<li>&apos;auth&apos; - Throttles based on auth ids.</li>
+<li>&apos;account&apos; - Throttles based on account ids for all users under a single account.</li>
+</ul>
+</li>
+</ol><p>Except for the scope, all throttle variables are required. By default, throttling is scoped to the account.</p><p>Here is a typical usage of the throttle configuration:</p>
+    </div>
+    <div class="col-md-7 col-sm-12 col-height  docs-code">
+      <pre><code class="lang-js"><span class="hljs-keyword">const</span> App = {
+  <span class="hljs-attr">version</span>: <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;./package.json&apos;</span>).version,
+  <span class="hljs-attr">platformVersion</span>: <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;zapier-platform-core&apos;</span>).version,
+
+  <span class="hljs-comment">// default throttle used for each action</span>
+  <span class="hljs-attr">throttle</span>: {
+    <span class="hljs-attr">window</span>: <span class="hljs-number">600</span>,
+    <span class="hljs-attr">limit</span>: <span class="hljs-number">50</span>,
+    <span class="hljs-attr">scope</span>: [<span class="hljs-string">&apos;account&apos;</span>],
+  },
+
+  <span class="hljs-attr">creates</span>: {
+    <span class="hljs-attr">upload_video</span>: {
+      <span class="hljs-attr">noun</span>: <span class="hljs-string">&apos;Video&apos;</span>,
+      <span class="hljs-attr">display</span>: {
+        <span class="hljs-attr">label</span>: <span class="hljs-string">&apos;Upload Video&apos;</span>,
+        <span class="hljs-attr">description</span>: <span class="hljs-string">&apos;Upload a video.&apos;</span>,
+      },
+      <span class="hljs-attr">operation</span>: {
+        <span class="hljs-attr">perform</span>: <span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {},
+        <span class="hljs-attr">inputFields</span>: [],
+        <span class="hljs-comment">// overwrites the default, for this action</span>
+        <span class="hljs-attr">throttle</span>: {
+          <span class="hljs-attr">window</span>: <span class="hljs-number">600</span>,
+          <span class="hljs-attr">limit</span>: <span class="hljs-number">5</span>,
+          <span class="hljs-attr">scope</span>: [<span class="hljs-string">&apos;account&apos;</span>],
+        },
+      },
+    },
+  },
+};
+
+<span class="hljs-built_in">module</span>.exports = App;
+
+</code></pre>
+    </div>
+  </div>
+</div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
       <h2 id="making-http-requests">Making HTTP Requests</h2>
diff --git a/packages/cli/README-source.md b/packages/cli/README-source.md
index d2ac7746f..e600e2e14 100644
--- a/packages/cli/README-source.md
+++ b/packages/cli/README-source.md
@@ -1153,6 +1153,29 @@ For example, you can access the `process.env` in your perform functions and in t
 > Note! Be sure to lazily access your environment variables - see [When to use placeholders or curlies?](#when-to-use-placeholders-or-curlies).
 
 
+## Adding Throttle Configuration
+
+*Added in v15.4.0.*
+
+When a throttle configuration is set for an action, Zapier uses it to apply throttling when the limit for the window timeframe is exceeded. It can be set at the root level and/or on an action. When set at the root level, it is the default throttle configuration used on each action of the integration. And when set in an action's operation object, the root-level default is overwritten for that action only.
+
+To throttle an action, you need to set a `throttle` object with the following variables:
+  1. `window [integer]`: The timeframe, in seconds, within which the system tracks the number of invocations for an action. The number of invocations begins at zero at the start of each window. It is an integer.
+  2. `limit [integer]`: The maximum number of invocations for an action, allowed within the timeframe window. It is an integer.
+  3. `scope [arrary]`: The granularity to throttle by. You can set the scope to one or more of the following options;
+        - 'user' - Throttles based on user ids.
+        - 'auth' - Throttles based on auth ids.
+        - 'account' - Throttles based on account ids for all users under a single account.
+
+Except for the scope, all throttle variables are required. By default, throttling is scoped to the account.
+
+Here is a typical usage of the throttle configuration:
+
+```js
+[insert-file:./snippets/throttle-configuration.js]
+```
+
+
 ## Making HTTP Requests
 
 There are two ways to make HTTP requests:
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 1f2d77ad6..46ff35de0 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -95,6 +95,7 @@ This doc describes the latest CLI version (**15.3.0**), as of this writing. If y
 - [Environment](#environment)
   * [Defining Environment Variables](#defining-environment-variables)
   * [Accessing Environment Variables](#accessing-environment-variables)
+- [Adding Throttle Configuration](#adding-throttle-configuration)
 - [Making HTTP Requests](#making-http-requests)
   * [Shorthand HTTP Requests](#shorthand-http-requests)
   * [Manual HTTP Requests](#manual-http-requests)
@@ -2154,6 +2155,62 @@ const App = {
 > Note! Be sure to lazily access your environment variables - see [When to use placeholders or curlies?](#when-to-use-placeholders-or-curlies).
 
 
+## Adding Throttle Configuration
+
+*Added in v15.4.0.*
+
+When a throttle configuration is set for an action, Zapier uses it to apply throttling when the limit for the window timeframe is exceeded. It can be set at the root level and/or on an action. When set at the root level, it is the default throttle configuration used on each action of the integration. And when set in an action's operation object, the root-level default is overwritten for that action only.
+
+To throttle an action, you need to set a `throttle` object with the following variables:
+  1. `window [integer]`: The timeframe, in seconds, within which the system tracks the number of invocations for an action. The number of invocations begins at zero at the start of each window. It is an integer.
+  2. `limit [integer]`: The maximum number of invocations for an action, allowed within the timeframe window. It is an integer.
+  3. `scope [arrary]`: The granularity to throttle by. You can set the scope to one or more of the following options;
+        - 'user' - Throttles based on user ids.
+        - 'auth' - Throttles based on auth ids.
+        - 'account' - Throttles based on account ids for all users under a single account.
+
+Except for the scope, all throttle variables are required. By default, throttling is scoped to the account.
+
+Here is a typical usage of the throttle configuration:
+
+```js
+const App = {
+  version: require('./package.json').version,
+  platformVersion: require('zapier-platform-core').version,
+
+  // default throttle used for each action
+  throttle: {
+    window: 600,
+    limit: 50,
+    scope: ['account'],
+  },
+
+  creates: {
+    upload_video: {
+      noun: 'Video',
+      display: {
+        label: 'Upload Video',
+        description: 'Upload a video.',
+      },
+      operation: {
+        perform: () => {},
+        inputFields: [],
+        // overwrites the default, for this action
+        throttle: {
+          window: 600,
+          limit: 5,
+          scope: ['account'],
+        },
+      },
+    },
+  },
+};
+
+module.exports = App;
+
+```
+
+
 ## Making HTTP Requests
 
 There are two ways to make HTTP requests:
diff --git a/packages/cli/docs/index.html b/packages/cli/docs/index.html
index fba7d925f..91f742f33 100644
--- a/packages/cli/docs/index.html
+++ b/packages/cli/docs/index.html
@@ -317,6 +317,7 @@
 <li><a href="#accessing-environment-variables">Accessing Environment Variables</a></li>
 </ul>
 </li>
+<li><a href="#adding-throttle-configuration">Adding Throttle Configuration</a></li>
 <li><a href="#making-http-requests">Making HTTP Requests</a><ul>
 <li><a href="#shorthand-http-requests">Shorthand HTTP Requests</a></li>
 <li><a href="#manual-http-requests">Manual HTTP Requests</a><ul>
@@ -528,6 +529,7 @@ <h2 id="table-of-contents">Table of Contents</h2>
 <li><a href="#accessing-environment-variables">Accessing Environment Variables</a></li>
 </ul>
 </li>
+<li><a href="#adding-throttle-configuration">Adding Throttle Configuration</a></li>
 <li><a href="#making-http-requests">Making HTTP Requests</a><ul>
 <li><a href="#shorthand-http-requests">Shorthand HTTP Requests</a></li>
 <li><a href="#manual-http-requests">Manual HTTP Requests</a><ul>
@@ -3640,6 +3642,67 @@ <h3 id="accessing-environment-variables">Accessing Environment Variables</h3>
     </div>
   </div>
 </div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <h2 id="adding-throttle-configuration">Adding Throttle Configuration</h2>
+    </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.4.0.</em></p><p>When a throttle configuration is set for an action, Zapier uses it to apply throttling when the limit for the window timeframe is exceeded. It can be set at the root level and/or on an action. When set at the root level, it is the default throttle configuration used on each action of the integration. And when set in an action&apos;s operation object, the root-level default is overwritten for that action only.</p><p>To throttle an action, you need to set a <code>throttle</code> object with the following variables:</p><ol>
+<li><code>window [integer]</code>: The timeframe, in seconds, within which the system tracks the number of invocations for an action. The number of invocations begins at zero at the start of each window. It is an integer.</li>
+<li><code>limit [integer]</code>: The maximum number of invocations for an action, allowed within the timeframe window. It is an integer.</li>
+<li><code>scope [arrary]</code>: The granularity to throttle by. You can set the scope to one or more of the following options;<ul>
+<li>&apos;user&apos; - Throttles based on user ids.</li>
+<li>&apos;auth&apos; - Throttles based on auth ids.</li>
+<li>&apos;account&apos; - Throttles based on account ids for all users under a single account.</li>
+</ul>
+</li>
+</ol><p>Except for the scope, all throttle variables are required. By default, throttling is scoped to the account.</p><p>Here is a typical usage of the throttle configuration:</p>
+    </div>
+    <div class="col-md-7 col-sm-12 col-height  docs-code">
+      <pre><code class="lang-js"><span class="hljs-keyword">const</span> App = {
+  <span class="hljs-attr">version</span>: <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;./package.json&apos;</span>).version,
+  <span class="hljs-attr">platformVersion</span>: <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;zapier-platform-core&apos;</span>).version,
+
+  <span class="hljs-comment">// default throttle used for each action</span>
+  <span class="hljs-attr">throttle</span>: {
+    <span class="hljs-attr">window</span>: <span class="hljs-number">600</span>,
+    <span class="hljs-attr">limit</span>: <span class="hljs-number">50</span>,
+    <span class="hljs-attr">scope</span>: [<span class="hljs-string">&apos;account&apos;</span>],
+  },
+
+  <span class="hljs-attr">creates</span>: {
+    <span class="hljs-attr">upload_video</span>: {
+      <span class="hljs-attr">noun</span>: <span class="hljs-string">&apos;Video&apos;</span>,
+      <span class="hljs-attr">display</span>: {
+        <span class="hljs-attr">label</span>: <span class="hljs-string">&apos;Upload Video&apos;</span>,
+        <span class="hljs-attr">description</span>: <span class="hljs-string">&apos;Upload a video.&apos;</span>,
+      },
+      <span class="hljs-attr">operation</span>: {
+        <span class="hljs-attr">perform</span>: <span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {},
+        <span class="hljs-attr">inputFields</span>: [],
+        <span class="hljs-comment">// overwrites the default, for this action</span>
+        <span class="hljs-attr">throttle</span>: {
+          <span class="hljs-attr">window</span>: <span class="hljs-number">600</span>,
+          <span class="hljs-attr">limit</span>: <span class="hljs-number">5</span>,
+          <span class="hljs-attr">scope</span>: [<span class="hljs-string">&apos;account&apos;</span>],
+        },
+      },
+    },
+  },
+};
+
+<span class="hljs-built_in">module</span>.exports = App;
+
+</code></pre>
+    </div>
+  </div>
+</div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
       <h2 id="making-http-requests">Making HTTP Requests</h2>
diff --git a/packages/cli/snippets/throttle-configuration.js b/packages/cli/snippets/throttle-configuration.js
new file mode 100644
index 000000000..349d79a63
--- /dev/null
+++ b/packages/cli/snippets/throttle-configuration.js
@@ -0,0 +1,33 @@
+const App = {
+  version: require('./package.json').version,
+  platformVersion: require('zapier-platform-core').version,
+
+  // default throttle used for each action
+  throttle: {
+    window: 600,
+    limit: 50,
+    scope: ['account'],
+  },
+
+  creates: {
+    upload_video: {
+      noun: 'Video',
+      display: {
+        label: 'Upload Video',
+        description: 'Upload a video.',
+      },
+      operation: {
+        perform: () => {},
+        inputFields: [],
+        // overwrites the default, for this action
+        throttle: {
+          window: 600,
+          limit: 5,
+          scope: ['account'],
+        },
+      },
+    },
+  },
+};
+
+module.exports = App;