docs(cli): document primary in outputFields

docs/index.html

@@ -2747,11 +2747,13 @@ <h2 id="output-fields">Output Fields</h2>
       <p>On each trigger, search, or create in the operation directive - you can provide an array of objects as fields under the <code>outputFields</code>. Output Fields are what users see when they select a field provided by your trigger, search or create to map it to another.</p><p>Output Fields are optional, but can be used to:</p><ul>
 <li>Define friendly labels for the returned fields. By default, we will <em>humanize</em> for example <code>my_key</code> as <em>My Key</em>.</li>
 <li>Make sure that custom fields that may not be found in every live sample and - since they&apos;re custom to the connected account - cannot be defined in the static sample, can still be mapped.</li>
+<li>(Added in v15.6.0) Define what field(s) can be used to uniquely identify and <a href="#dedupe">deduplicate</a> items returned by a polling trigger call.</li>
 </ul><p>The <a href="https://github.com/zapier/zapier-platform/blob/main/packages/schema/docs/build/schema.md#fieldschema">schema</a> for <code>outputFields</code> is shared with <code>inputFields</code> but only the <code>key</code>, <code>label</code>, <code>type</code>, and <code>required</code> properties are relevant:</p><ul>
 <li><code>key</code> - includes the field when not present in the live sample. When no <code>label</code> property is provided, <code>key</code> will be <em>humanized</em> and displayed as the field name.</li>
 <li><code>label</code> - defines the field name displayed to users.</li>
 <li><code>type</code> - defines the type for static sample data. A <a href="https://platform.zapier.com/docs/integration-checks-reference#d024---static-sample-respects-output-field-definition">validation warning</a> will be displayed if the static sample does not match the specified type.</li>
 <li><code>required</code> - defines whether the field is required in static sample data. A <a href="https://platform.zapier.com/docs/integration-checks-reference#d024---static-sample-respects-output-field-definition">validation warning</a> will be displayed if the value is true and the static sample does not contain the field.</li>
+<li><code>primary</code> - defines whether the field is part of the primary key for polling trigger <a href="#dedupe">deduplication</a>.</li>
 </ul><p>Custom/Dynamic Output Fields are defined in the same way as <a href="#customdynamic-fields">Custom/Dynamic Input Fields</a>.</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
@@ -5608,7 +5610,7 @@ <h3 id="how-does-deduplication-work">How does deduplication work?</h3>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p>Each time a polling Zap runs, Zapier needs to decide which of the items in the response should trigger the zap. To do this, we compare the <code>id</code>s to all those we&apos;ve seen before, trigger on new objects, and update the list of seen <code>id</code>s. When a Zap is turned on, we initialize the list of seen <code>id</code>s with a single poll. When it&apos;s turned off, we clear that list. For this reason, it&apos;s important that calls to a polling endpoint always return the newest items.</p><p>For example, the initial poll returns objects 4, 5, and 6 (where a higher <code>id</code> is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects.</p><p>There&apos;s a more in-depth explanation <a href="https://platform.zapier.com/legacy/dedupe">here</a>.</p>
+      <p>Each time a polling Zap runs, Zapier extracts a unique &quot;primary key&quot; for each item in the response. Zapier needs to decide which of the items should trigger the Zap. To do this, we compare the primary keys to all those we&apos;ve seen before, trigger on new objects, and update the list of seen primary keys. When a Zap is turned on, we initialize the list of seen primary keys with a single poll. When it&apos;s turned off, we clear that list. For this reason, it&apos;s important that calls to a polling endpoint always return the newest items.</p><p>For example, the initial poll returns objects 4, 5, and 6 (where a higher primary key is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects.</p><p>By default, the primary key is the item&apos;s <code>id</code> field. Since v15.6.0, you can customize the primary by setting any <code>outputFields</code> to true.</p><p>There&apos;s a more in-depth explanation <a href="https://platform.zapier.com/build/deduplication">here</a>.</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
 
@@ -5639,6 +5641,36 @@ <h3 id="why-are-my-triggers-complaining-if-i-dont-provide-an-explicit-id-field">
     </div>
   </div>
 </div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <p>Since v15.6.0, instead of using the default <code>id</code> field, you can also define one or more <code>outputFields</code> as <code>primary</code>. For example:</p>
+    </div>
+    <div class="col-md-7 col-sm-12 col-height  docs-code">
+      <pre><code class="lang-js">{
+  <span class="hljs-attr">triggers</span>: {
+    <span class="hljs-attr">recipe</span>: {
+      <span class="hljs-attr">operation</span>: {
+        <span class="hljs-attr">outputField</span>: [
+          { <span class="hljs-attr">key</span>: <span class="hljs-string">&apos;userId&apos;</span>, <span class="hljs-attr">primary</span>: <span class="hljs-literal">true</span> },
+          { <span class="hljs-attr">key</span>: <span class="hljs-string">&apos;slug&apos;</span>, <span class="hljs-attr">primary</span>: <span class="hljs-literal">true</span> },
+        ]
+      }
+    }
+  }
+}
+</code></pre>
+    </div>
+  </div>
+</div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <p>will tell Zapier to use <code>(userId, slug)</code> as the unique primary key to deduplicate items when running a polling trigger.</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="node-x-no-longer-supported">Node X No Longer Supported</h3>

packages/cli/README-source.md

@@ -786,16 +786,17 @@ On each trigger, search, or create in the operation directive - you can provide
 
 Output Fields are optional, but can be used to:
 
-
 - Define friendly labels for the returned fields. By default, we will *humanize* for example `my_key` as *My Key*.
 - Make sure that custom fields that may not be found in every live sample and - since they're custom to the connected account - cannot be defined in the static sample, can still be mapped.
+- (Added in v15.6.0) Define what field(s) can be used to uniquely identify and [deduplicate](#dedupe) items returned by a polling trigger call.
 
 The [schema](https://github.com/zapier/zapier-platform/blob/main/packages/schema/docs/build/schema.md#fieldschema) for `outputFields` is shared with `inputFields` but only the `key`, `label`, `type`, and `required` properties are relevant:
 
 - `key` - includes the field when not present in the live sample. When no `label` property is provided, `key` will be *humanized* and displayed as the field name.
 - `label` - defines the field name displayed to users.
 - `type` - defines the type for static sample data. A [validation warning](https://platform.zapier.com/docs/integration-checks-reference#d024---static-sample-respects-output-field-definition) will be displayed if the static sample does not match the specified type.
 - `required` - defines whether the field is required in static sample data. A [validation warning](https://platform.zapier.com/docs/integration-checks-reference#d024---static-sample-respects-output-field-definition) will be displayed if the value is true and the static sample does not contain the field.
+- `primary` - defines whether the field is part of the primary key for polling trigger [deduplication](#dedupe).
 
 Custom/Dynamic Output Fields are defined in the same way as [Custom/Dynamic Input Fields](#customdynamic-fields).
 
@@ -2052,11 +2053,13 @@ Lastly, you need to set `canPaginate` to `true` in your polling definition (per
 <a id="dedup"></a>
 ### How does deduplication work?
 
-Each time a polling Zap runs, Zapier needs to decide which of the items in the response should trigger the zap. To do this, we compare the `id`s to all those we've seen before, trigger on new objects, and update the list of seen `id`s. When a Zap is turned on, we initialize the list of seen `id`s with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items.
+Each time a polling Zap runs, Zapier extracts a unique "primary key" for each item in the response. Zapier needs to decide which of the items should trigger the Zap. To do this, we compare the primary keys to all those we've seen before, trigger on new objects, and update the list of seen primary keys. When a Zap is turned on, we initialize the list of seen primary keys with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items.
+
+For example, the initial poll returns objects 4, 5, and 6 (where a higher primary key is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects.
 
-For example, the initial poll returns objects 4, 5, and 6 (where a higher `id` is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects.
+By default, the primary key is the item's `id` field. Since v15.6.0, you can customize the primary by setting any `outputFields` to true.
 
-There's a more in-depth explanation [here](https://platform.zapier.com/legacy/dedupe).
+There's a more in-depth explanation [here](https://platform.zapier.com/build/deduplication).
 
 ### Why are my triggers complaining if I don't provide an explicit `id` field?
 
@@ -2071,6 +2074,25 @@ return items.map((item) => {
 });
 ```
 
+Since v15.6.0, instead of using the default `id` field, you can also define one or more `outputFields` as `primary`. For example:
+
+```js
+{
+  triggers: {
+    recipe: {
+      operation: {
+        outputField: [
+          { key: 'userId', primary: true },
+          { key: 'slug', primary: true },
+        ]
+      }
+    }
+  }
+}
+```
+
+will tell Zapier to use `(userId, slug)` as the unique primary key to deduplicate items when running a polling trigger.
+
 ### Node X No Longer Supported
 
 If you're seeing errors like the following:

packages/cli/README.md

@@ -1677,16 +1677,17 @@ On each trigger, search, or create in the operation directive - you can provide
 
 Output Fields are optional, but can be used to:
 
-
 - Define friendly labels for the returned fields. By default, we will *humanize* for example `my_key` as *My Key*.
 - Make sure that custom fields that may not be found in every live sample and - since they're custom to the connected account - cannot be defined in the static sample, can still be mapped.
+- (Added in v15.6.0) Define what field(s) can be used to uniquely identify and [deduplicate](#dedupe) items returned by a polling trigger call.
 
 The [schema](https://github.com/zapier/zapier-platform/blob/main/packages/schema/docs/build/schema.md#fieldschema) for `outputFields` is shared with `inputFields` but only the `key`, `label`, `type`, and `required` properties are relevant:
 
 - `key` - includes the field when not present in the live sample. When no `label` property is provided, `key` will be *humanized* and displayed as the field name.
 - `label` - defines the field name displayed to users.
 - `type` - defines the type for static sample data. A [validation warning](https://platform.zapier.com/docs/integration-checks-reference#d024---static-sample-respects-output-field-definition) will be displayed if the static sample does not match the specified type.
 - `required` - defines whether the field is required in static sample data. A [validation warning](https://platform.zapier.com/docs/integration-checks-reference#d024---static-sample-respects-output-field-definition) will be displayed if the value is true and the static sample does not contain the field.
+- `primary` - defines whether the field is part of the primary key for polling trigger [deduplication](#dedupe).
 
 Custom/Dynamic Output Fields are defined in the same way as [Custom/Dynamic Input Fields](#customdynamic-fields).
 
@@ -3543,11 +3544,13 @@ Lastly, you need to set `canPaginate` to `true` in your polling definition (per
 <a id="dedup"></a>
 ### How does deduplication work?
 
-Each time a polling Zap runs, Zapier needs to decide which of the items in the response should trigger the zap. To do this, we compare the `id`s to all those we've seen before, trigger on new objects, and update the list of seen `id`s. When a Zap is turned on, we initialize the list of seen `id`s with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items.
+Each time a polling Zap runs, Zapier extracts a unique "primary key" for each item in the response. Zapier needs to decide which of the items should trigger the Zap. To do this, we compare the primary keys to all those we've seen before, trigger on new objects, and update the list of seen primary keys. When a Zap is turned on, we initialize the list of seen primary keys with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items.
+
+For example, the initial poll returns objects 4, 5, and 6 (where a higher primary key is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects.
 
-For example, the initial poll returns objects 4, 5, and 6 (where a higher `id` is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects.
+By default, the primary key is the item's `id` field. Since v15.6.0, you can customize the primary by setting any `outputFields` to true.
 
-There's a more in-depth explanation [here](https://platform.zapier.com/legacy/dedupe).
+There's a more in-depth explanation [here](https://platform.zapier.com/build/deduplication).
 
 ### Why are my triggers complaining if I don't provide an explicit `id` field?
 
@@ -3562,6 +3565,25 @@ return items.map((item) => {
 });
 ```
 
+Since v15.6.0, instead of using the default `id` field, you can also define one or more `outputFields` as `primary`. For example:
+
+```js
+{
+  triggers: {
+    recipe: {
+      operation: {
+        outputField: [
+          { key: 'userId', primary: true },
+          { key: 'slug', primary: true },
+        ]
+      }
+    }
+  }
+}
+```
+
+will tell Zapier to use `(userId, slug)` as the unique primary key to deduplicate items when running a polling trigger.
+
 ### Node X No Longer Supported
 
 If you're seeing errors like the following: