feat: add in-app feed response filter docs (#349)

* feat: add in-app feed response filter docs

* chore: run formatter

* fix: formatting glitch

.github/pull_request_template.md

@@ -1,13 +1,18 @@
 ### Description
+
 ** Describe what, why and how of the changes clearly and concisely. Add any additional useful context or info, as necessary. **
 
 ### Todos
+
 ** List any todo items necessary before merging, if any. Delete if none. **
+
 - [ ] Sample todo item 1
 - [ ] Sample todo item 2
 
 ### Tasks
+
 ** Link to task(s) which this PR corresponds to. Example: [KNO-54](https://linear.app/knock/issue/KNO-54/create-a-pr-template) **
 
 ### Screenshots
+
 ** Attach any screenshots or recordings to visually illustrate the changes, as necessary. Delete if not relevant. **

content/cli.mdx

@@ -939,7 +939,7 @@ List all commits in the environment. Use an `--environment` flag to specify the
     type="string"
     description="The environment to use. Defaults to development."
   />
-    <Attribute
+  <Attribute
     name="--[no-]promoted"
     type="boolean"
     description="Show only promoted or unpromoted changes between the given environment and the subsequent environment."
@@ -1047,7 +1047,7 @@ Note:
     type="string"
     description="The destination environment."
   />
-   <Attribute
+  <Attribute
     name="--only"
     type="string"
     description="The target commit id to promote to the subsequent environment."

content/concepts/schedules.mdx

@@ -1,6 +1,6 @@
 ---
 title: Schedules
-description: Learn how to use Schedules to run workflows at set times for your recipients in a recurring or one-off manner. 
+description: Learn how to use Schedules to run workflows at set times for your recipients in a recurring or one-off manner.
 tags:
   [
     "crons",
@@ -19,8 +19,8 @@ A schedule allows you to automatically trigger a workflow at a given time for on
 
 Some examples of where you might reach for a schedule:
 
-* A digest notification where your users can select the frequency in which they wish to receive the digest (every day, every week, every month).
-* A reminder notification for a specific event or deadline, sent only once at a given date and time.
+- A digest notification where your users can select the frequency in which they wish to receive the digest (every day, every week, every month).
+- A reminder notification for a specific event or deadline, sent only once at a given date and time.
 
 ## How schedules work
 
@@ -71,16 +71,15 @@ const schedules = await knock.workflows.createSchedules("park-alert", {
 
 ### Schedule properties
 
-| Variable       | Type                  | Description                                                                                                                                    |
-| -------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `recipients`   | RecipientIdentifier[] | One or more recipient identifiers, or complete recipients to be upserted.                                                                      |
-| `workflow`     | string                | The workflow to trigger.                                                                                                                       |
-| `repeats`      | ScheduleRepeat[]      | A list of one or more repeats (see below). Required if you're creating a recurring schedule.                                                                                                     |
-| `data`         | map                   | Custom data to pass to every workflow trigger.                                                                                                 |
-| `tenant`       | string                | A tenant to pass to the workflow trigger.                                                                                                      |
-| `actor`        | RecipientIdentifier   | An identifier of an actor, or a complete actor to be upserted.                                                                                 |
-| `scheduled_at` | utc_datetime          | A UTC datetime representing the start moment for the recurring schedule, or the exact and only execution moment for the non-recurring schedule.|
-
+| Variable       | Type                  | Description                                                                                                                                     |
+| -------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `recipients`   | RecipientIdentifier[] | One or more recipient identifiers, or complete recipients to be upserted.                                                                       |
+| `workflow`     | string                | The workflow to trigger.                                                                                                                        |
+| `repeats`      | ScheduleRepeat[]      | A list of one or more repeats (see below). Required if you're creating a recurring schedule.                                                    |
+| `data`         | map                   | Custom data to pass to every workflow trigger.                                                                                                  |
+| `tenant`       | string                | A tenant to pass to the workflow trigger.                                                                                                       |
+| `actor`        | RecipientIdentifier   | An identifier of an actor, or a complete actor to be upserted.                                                                                  |
+| `scheduled_at` | utc_datetime          | A UTC datetime representing the start moment for the recurring schedule, or the exact and only execution moment for the non-recurring schedule. |
 
 ### ScheduleRepeat properties
 
@@ -240,7 +239,9 @@ Knock supports a `timezone` property on the recipient that automatically makes a
   emoji="💡"
   text={
     <>
-      <span className="font-bold">Note</span>: executing schedules in recipient timezones is currently only supported by <a href="/designing-workflows/step-conditions">recurring schedules</a>.
+      <span className="font-bold">Note</span>: executing schedules in recipient
+      timezones is currently only supported by{" "}
+      <a href="/designing-workflows/step-conditions">recurring schedules</a>.
     </>
   }
 />

content/getting-started/knock-and-postman.md

@@ -13,7 +13,7 @@ In this guide you'll fork the Knock collection into your Postman workspace and c
 
 1. Install [Postman](https://www.postman.com/downloads/) if you don't have it already.
 2. [Fork the Knock API Postman collection](https://god.gw.postman.com/run-collection/10721026-cd261902-9249-4714-b7d3-896c15987fa5?action=collection%2Ffork&collection-url=entityId%3D10721026-cd261902-9249-4714-b7d3-896c15987fa5%26entityType%3Dcollection%26workspaceId%3De0ad9a88-e3dd-462b-8c44-695c9c10b8e5#?env%5BKnock%20environment%20template%5D=W3sia2V5IjoiYmFzZV91cmwiLCJ2YWx1ZSI6Imh0dHBzOi8vYXBpLmtub2NrLmFwcCIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoic2VjcmV0X2tleSIsInZhbHVlIjoic2tfdGVzdF94eHh4IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJwdWJsaWNfa2V5IiwidmFsdWUiOiJwa190ZXN0X3h4eHgiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6IndvcmtmbG93X2tleSIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJyZWNpcGllbnRfdXNlcl9pZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJhY3Rvcl91c2VyX2lkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImZlZWRfaWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidXNlcl9pZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJ1c2VyX25hbWUiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidXNlcl9lbWFpbCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJ1c2VyX2F2YXRhcl91cmwiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoicHJlZmVyZW5jZV9zZXRfaWQiLCJ2YWx1ZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfV0=). We recommend forking the collection (as opposed to creating a copy) so that you can pull changes we make to the source collection.
-    * We provide a separate [Management API Postman collection](https://www.postman.com/knock-labs/workspace/knock-public-workspace/collection/15616728-9ed6000c-13bc-43f5-a2cf-db6daea256bd?action=share&creator=15616728&active-environment=15616728-6df39335-c6f9-4c9d-99d5-73e3c7ffe524). You can use use this to test our [Management API](https://docs.knock.app/mapi#overview).
+   - We provide a separate [Management API Postman collection](https://www.postman.com/knock-labs/workspace/knock-public-workspace/collection/15616728-9ed6000c-13bc-43f5-a2cf-db6daea256bd?action=share&creator=15616728&active-environment=15616728-6df39335-c6f9-4c9d-99d5-73e3c7ffe524). You can use use this to test our [Management API](https://docs.knock.app/mapi#overview).
 
 ## Configure your Knock environments in Postman
 

content/guides/building-recurring-digests.mdx

@@ -104,7 +104,6 @@ There are new notifications waiting for you to review. Please go into the app to
       <strong>Note</strong>: you'll need to configure an email channel via a
       provider in order to start sending emails with Knock. You can read more on{" "}
       <a href="/integrations/email/overview">configuring email channels here</a>
-      .
     </>
   }
 />

content/guides/customer-webhooks.mdx

@@ -1,5 +1,5 @@
 ---
-title: Building customer-facing, configurable webhooks with Knock 
+title: Building customer-facing, configurable webhooks with Knock
 description: Learn how to use Knock to send per-customer configurable webhooks as part of your notification workflows.
 tags: ["webhooks", "webhooks as a service"]
 section: Guides
@@ -18,7 +18,7 @@ In Knock, we’ll model this as follows:
 
 First we’ll upsert the project as an object in Knock. We’re putting the project under a `projects` collection.
 
-```js Upsert our project object 
+```js Upsert our project object
 const project = await knock.objects.set("projects", "project-1", {
   name: "My project",
 });
@@ -33,7 +33,7 @@ const webhookId = "some-unique-id";
 // Create the webhook object with the configuration
 const projectWebhook = await knock.objects.set("project_webhooks", webhookId, {
   events: ["project:created"],
-	url: "https://some-url.com/incoming/webhook",
+  url: "https://some-url.com/incoming/webhook",
 });
 
 // Associate the webhook with the project
@@ -46,14 +46,14 @@ If at any point we need to list all of the configured webhooks for a given proje
 
 ```js List webhooks for a given project
 const { entries: webhookSubscriptions } = await knock.objects.listSubscriptions(
-	"projects", 
-	"project-1"
+  "projects",
+  "project-1",
 );
 ```
 
 ## Configuring an HTTP channel
 
-Now we’re going to configure our Webhook HTTP channel in Knock. You can learn how to configure a Webhook HTTP channel in our [webhook channel overview](/integrations/webhook/overview). 
+Now we’re going to configure our Webhook HTTP channel in Knock. You can learn how to configure a Webhook HTTP channel in our [webhook channel overview](/integrations/webhook/overview).
 
 Next, we’ll configure the webhook request for our new webhook channel. For the channel URL we’re going to configure it as `{{ recipient.url }}` which tells Knock to use the URL configured on the webhook recipient object:
 
@@ -66,7 +66,7 @@ And for the body of the payload that we send per webhook event, we’ll use the
   "type": "{{ event_type }}",
   "data": {{ payload }},
   "created_at": {{ timestamp }}
-} 
+}
 ```
 
 ## Building your webhook notification workflow
@@ -85,17 +85,15 @@ We don’t need to customize any of the data sent in the webhook channel, so we
 
 ## Triggering your webhook notification workflow
 
-Now our workflow is configured, we can trigger it via the API. We’ll pass the `project` as a recipient to the workflow, which will automatically trigger our workflow to execute *for all webhooks configured*.
+Now our workflow is configured, we can trigger it via the API. We’ll pass the `project` as a recipient to the workflow, which will automatically trigger our workflow to execute _for all webhooks configured_.
 
 ```js Trigger workflow for our project
 await knock.workflows.trigger("workflow-with-webhook-step", {
-	data: {
-		event_type: eventType,
-		payload: eventPayloadData,
-	},
-	recipients: [
-		{ collection: "projects", id: "project-1" }
-	],
+  data: {
+    event_type: eventType,
+    payload: eventPayloadData,
+  },
+  recipients: [{ collection: "projects", id: "project-1" }],
 });
 ```
 
@@ -114,15 +112,15 @@ You might want to provide a way to notify your customers that their webhooks are
 ## Frequently asked questions
 
 **How do I power different types of webhook events, should those be different notification workflows or a single workflow?**
-The answer here really depends on how different the notifications around each event type need to be. You should consider structuring each event type as a different workflow if the types of notifications sent in each event type differ a lot, or if the templates between event types are sufficiently different. 
+The answer here really depends on how different the notifications around each event type need to be. You should consider structuring each event type as a different workflow if the types of notifications sent in each event type differ a lot, or if the templates between event types are sufficiently different.
 
 **How do I conditionally send to only to webhook objects?**
-If you need to limit the execution of the workflow steps you can add a trigger condition onto your webhook channel steps that will only send to: 
+If you need to limit the execution of the workflow steps you can add a trigger condition onto your webhook channel steps that will only send to:
 
 - `recipient.__typename` is equal to `Object`
 - `recipient.collection` is equal to `project_webhooks`
 
 **How do I conditionally allow certain event types on my webhooks?**
 You can store an `event_types` property on your webhook object and use a trigger condition to express whether or not the step should be executed (as an allow list).
 
-- `recipient.event_types` contains `some:event`
+- `recipient.event_types` contains `some:event`

content/in-app-ui/angular/overview.mdx

@@ -4,7 +4,7 @@ description: Learn more about the in-app notifications experiences you can build
 section: Building in-app UI
 ---
 
-Today we do not have Knock-built, out-of-the-box Angular components for in-app notifications UI. 
+Today we do not have Knock-built, out-of-the-box Angular components for in-app notifications UI.
 
 Our Knock community built this [Angular in-app feed example](https://github.com/knocklabs/angular-in-app-feed-example) you can use to get started with an Angular in-app feed in your own application.
 

content/integrations/in-app/knock.mdx

@@ -38,3 +38,56 @@ Note that the functionality above is just the default for what we've provided in
 Sometimes a user wants to remove a notification from their feed altogether. This is where notification archiving comes in. When a notification is archived, it is removed from the feed and is no longer visible to the end user.
 
 In the Knock in-app feed, a message can be archived by clicking the "x" in the top-right corner of a given notification. The in-app feed component doesn't give users a way to see their archived notifications out-of-the-box, but if you'd like to incorporate this into your own in-app feed you can use the `archived: only` parameter on the [GET feed request](/reference#get-feed).
+
+## Customizing API response content
+
+By default, the [in-app feed API](/reference#get-feed) will return:
+
+- One or more actors associated with each in-app notification (when set), including all custom properties under each actor
+- All of the public variables (note: secret variables are never returned)
+- The entire workflow trigger data associated with each in-app notification
+- The recipient associated with each notification, including all custom properties set
+
+In some situations, you may need control over exactly what the in-app feed API returns. This is where our API response filter can be used to completely customize the keys returned for the entities in your in-app feed responses.
+
+| Property  | Description                                                                    |
+| --------- | ------------------------------------------------------------------------------ |
+| vars      | Apply a filter to the environment variables returned                           |
+| actor     | Apply a filter to all actors returned from the feed endpoint                   |
+| recipient | Apply a filter to the recipient returned from the feed endpoint                |
+| data      | Apply a filter to workflow trigger data returned from the in-app feed endpoint |
+
+Each property accepts the following:
+
+- A boolean to indicate whether this entity should be omitted or included, entirely (defaults to `true`).
+- An object with either `except` or `only` key paths for keys to exclude or include. Note: a nested keypath can be given using a `.`.
+
+### Example: customizing the actor data
+
+As an example, if you want to customize the properties returned under an actor to only include `id`, `name`, and `avatar` you can set a response filter such as:
+
+```json
+{
+  "actor": {
+    "only": ["id", "name", "avatar"]
+  }
+}
+```
+
+If you want to omit certain keys from the actor you can use the `except` keyword:
+
+```json
+{
+  "actor": {
+    "except": ["email", "phone_number", "credit_card.last4"]
+  }
+}
+```
+
+Or, if you want to exclude the actor from rendering you can set:
+
+```json
+{
+  "actor": false
+}
+```

content/manage-your-account/data-obfuscation.mdx

@@ -5,15 +5,16 @@ tags: ["privacy", "data controls", "security", "privacy controls"]
 section: Manage your account
 ---
 
-Enable customer data obfuscation on a per-environment basis to determine what data your team members can see in the Knock dashboard. 
+Enable customer data obfuscation on a per-environment basis to determine what data your team members can see in the Knock dashboard.
 
 ## Overview
-When you choose Knock to power your notifications, you're also choosing to trust us with your customer data and the data you pass in your notifications. This is why [security](/security) is a foundational priority for us at Knock, and it's also why we built our customer data obfuscation controls. 
 
-With customer data obfuscation controls, the Knock dashboard automatically hides any data that might contain either user PII or customer proprietary data. This means that the only data your team members will see in the Knock dashboard is anonymous data such as UUIDs. Customer data obfuscation is managed via our backend, so users won't be able to get at this data through their browser consoles. 
+When you choose Knock to power your notifications, you're also choosing to trust us with your customer data and the data you pass in your notifications. This is why [security](/security) is a foundational priority for us at Knock, and it's also why we built our customer data obfuscation controls.
 
-Customer data obfuscation is enabled on a [per-environment](/send-and-manage-data/environments) basis. This means you can obfuscate your customer data in your production environment, while still retaining access to your internal data in development environments for easy testing and debugging. 
+With customer data obfuscation controls, the Knock dashboard automatically hides any data that might contain either user PII or customer proprietary data. This means that the only data your team members will see in the Knock dashboard is anonymous data such as UUIDs. Customer data obfuscation is managed via our backend, so users won't be able to get at this data through their browser consoles.
+
+Customer data obfuscation is enabled on a [per-environment](/send-and-manage-data/environments) basis. This means you can obfuscate your customer data in your production environment, while still retaining access to your internal data in development environments for easy testing and debugging.
 
 ![A preview of customer data obfuscation enabled](/images/manage-your-account/customer-data-obfuscation.png)
 
-To enable customer data obfuscation, go to the Knock dashboard > Settings > Environments. Select the "..." for the environment you'd like to configure and click "Edit environment."
+To enable customer data obfuscation, go to the Knock dashboard > Settings > Environments. Select the "..." for the environment you'd like to configure and click "Edit environment."