feat: add in-app feed response filter docs

.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

@@ -103,8 +103,7 @@ 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>
-      .
+      <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
+}
+```