@knocklabs/node 1.34.0 → 1.36.0

package/src/resources/messages/messages.ts

@@ -1,6 +1,8 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
+import * as MessagesAPI from './messages';
+import * as Shared from '../shared';
 import * as BatchAPI from './batch';
 import {
   Batch,
@@ -18,6 +20,7 @@ import {
   BatchMarkAsUnreadResponse,
   BatchMarkAsUnseenParams,
   BatchMarkAsUnseenResponse,
+  BatchMessagesStatusRequest,
   BatchUnarchiveParams,
   BatchUnarchiveResponse,
 } from './batch';
@@ -86,12 +89,12 @@ export class Messages extends APIResource {
    *
    * @example
    * ```ts
-   * const response = await client.messages.getContent(
+   * const messageContents = await client.messages.getContent(
    *   'message_id',
    * );
    * ```
    */
-  getContent(messageID: string, options?: RequestOptions): APIPromise<MessageGetContentResponse> {
+  getContent(messageID: string, options?: RequestOptions): APIPromise<MessageContents> {
     return this._client.get(path`/v1/messages/${messageID}/content`, options);
   }
 
@@ -321,6 +324,21 @@ export interface Activity {
   updated_at?: string;
 }
 
+/**
+ * A paginated list of messages.
+ */
+export interface ListMessagesResponse {
+  /**
+   * A list of messages.
+   */
+  items: Array<Message>;
+
+  /**
+   * Pagination information for a list of resources.
+   */
+  page_info: Shared.PageInfo;
+}
+
 /**
  * Represents a single message that was generated by a workflow for a given
  * channel.
@@ -424,8 +442,9 @@ export interface Message {
   read_at?: string | null;
 
   /**
-   * Recipient contact information captured at email send time. Null for non-email
-   * channels.
+   * The destination the message was delivered to, captured at send time. Email
+   * channels carry `email`/`name`; chat channels carry the destination `channel_id`
+   * or `user_id`, or `via_incoming_webhook`. Null when no snapshot was captured.
    */
   recipient_snapshot?: Message.RecipientSnapshot | null;
 
@@ -537,177 +556,42 @@ export namespace Message {
   }
 
   /**
-   * Recipient contact information captured at email send time. Null for non-email
-   * channels.
+   * The destination the message was delivered to, captured at send time. Email
+   * channels carry `email`/`name`; chat channels carry the destination `channel_id`
+   * or `user_id`, or `via_incoming_webhook`. Null when no snapshot was captured.
    */
   export interface RecipientSnapshot {
     /**
-     * The email address the message was delivered to
-     */
-    email?: string;
-
-    /**
-     * The recipient name at send time
-     */
-    name?: string | null;
-  }
-}
-
-/**
- * A message delivery log contains a `request` from Knock to a downstream provider
- * and the `response` that was returned.
- */
-export interface MessageDeliveryLog {
-  /**
-   * The unique identifier for the message delivery log.
-   */
-  id: string;
-
-  /**
-   * The typename of the schema.
-   */
-  __typename: string;
-
-  /**
-   * The ID of the environment in which the message delivery occurred.
-   */
-  environment_id: string;
-
-  /**
-   * Timestamp when the message delivery log was created.
-   */
-  inserted_at: string;
-
-  /**
-   * A message delivery log request.
-   */
-  request: MessageDeliveryLog.Request;
-
-  /**
-   * A message delivery log response.
-   */
-  response: MessageDeliveryLog.Response;
-
-  /**
-   * The name of the service that processed the delivery.
-   */
-  service_name: string;
-}
-
-export namespace MessageDeliveryLog {
-  /**
-   * A message delivery log request.
-   */
-  export interface Request {
-    /**
-     * The body content that was sent with the request.
-     */
-    body?: string | { [key: string]: unknown };
-
-    /**
-     * The headers that were sent with the request.
-     */
-    headers?: { [key: string]: unknown } | null;
-
-    /**
-     * The host to which the request was sent.
-     */
-    host?: string;
-
-    /**
-     * The HTTP method used for the request.
+     * The chat channel the message was delivered to (chat channels)
      */
-    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    channel_id?: string | null;
 
     /**
-     * The path of the URL that was requested.
+     * The email address the message was delivered to (email channels)
      */
-    path?: string;
-
-    /**
-     * The query string of the URL that was requested.
-     */
-    query?: string | null;
-  }
+    email?: string | null;
 
-  /**
-   * A message delivery log response.
-   */
-  export interface Response {
     /**
-     * The body content that was received with the response.
+     * The recipient name at send time (email channels)
      */
-    body?: string | { [key: string]: unknown };
+    name?: string | null;
 
     /**
-     * The headers that were received with the response.
+     * The chat user the message was direct-messaged to (chat channels)
      */
-    headers?: { [key: string]: unknown } | null;
+    user_id?: string | null;
 
     /**
-     * The HTTP status code of the response.
+     * Whether the chat message was delivered via an incoming webhook
      */
-    status?: number;
+    via_incoming_webhook?: boolean | null;
   }
 }
 
-/**
- * A message event. Occurs when a message
- * [delivery or engagement status](/send-notifications/message-statuses) changes.
- */
-export interface MessageEvent {
-  /**
-   * The unique identifier for the message event.
-   */
-  id: string;
-
-  /**
-   * The typename of the schema.
-   */
-  __typename: string;
-
-  /**
-   * Timestamp when the event was created.
-   */
-  inserted_at: string;
-
-  /**
-   * A reference to a recipient, either a user identifier (string) or an object
-   * reference (ID, collection).
-   */
-  recipient: RecipientsAPI.RecipientReference;
-
-  /**
-   * The type of event that occurred.
-   */
-  type:
-    | 'message.read'
-    | 'message.sent'
-    | 'message.seen'
-    | 'message.created'
-    | 'message.queued'
-    | 'message.delivered'
-    | 'message.bounced'
-    | 'message.undelivered'
-    | 'message.not_sent'
-    | 'message.delivery_attempted'
-    | 'message.archived'
-    | 'message.link_clicked'
-    | 'message.interacted'
-    | 'message.unseen'
-    | 'message.unread'
-    | 'message.unarchived';
-
-  /**
-   * The data associated with the message event. Only present for some event types.
-   */
-  data?: { [key: string]: unknown } | null;
-}
-
 /**
  * The content of a message.
  */
-export interface MessageGetContentResponse {
+export interface MessageContents {
   /**
    * The typename of the schema.
    */
@@ -717,11 +601,11 @@ export interface MessageGetContentResponse {
    * Content data specific to the channel type.
    */
   data:
-    | MessageGetContentResponse.MessageEmailContent
-    | MessageGetContentResponse.MessageSMSContent
-    | MessageGetContentResponse.MessagePushContent
-    | MessageGetContentResponse.MessageChatContent
-    | MessageGetContentResponse.MessageInAppFeedContent;
+    | MessageContents.MessageEmailContent
+    | MessageContents.MessageSMSContent
+    | MessageContents.MessagePushContent
+    | MessageContents.MessageChatContent
+    | MessageContents.MessageInAppFeedContent;
 
   /**
    * Timestamp when the message content was created.
@@ -734,7 +618,7 @@ export interface MessageGetContentResponse {
   message_id: string;
 }
 
-export namespace MessageGetContentResponse {
+export namespace MessageContents {
   /**
    * The content of an email message.
    */
@@ -916,82 +800,229 @@ export namespace MessageGetContentResponse {
     /**
      * The blocks of the message in an app feed.
      */
-    blocks: Array<
-      | MessageInAppFeedContent.MessageInAppFeedContentBlock
-      | MessageInAppFeedContent.MessageInAppFeedButtonSetBlock
-    >;
+    blocks: Array<MessagesAPI.MessageInAppFeedContentBlock | MessagesAPI.MessageInAppFeedButtonSetBlock>;
   }
+}
+
+/**
+ * A message delivery log contains a `request` from Knock to a downstream provider
+ * and the `response` that was returned.
+ */
+export interface MessageDeliveryLog {
+  /**
+   * The unique identifier for the message delivery log.
+   */
+  id: string;
+
+  /**
+   * The typename of the schema.
+   */
+  __typename: string;
+
+  /**
+   * The ID of the environment in which the message delivery occurred.
+   */
+  environment_id: string;
+
+  /**
+   * Timestamp when the message delivery log was created.
+   */
+  inserted_at: string;
+
+  /**
+   * A message delivery log request.
+   */
+  request: MessageDeliveryLog.Request;
+
+  /**
+   * A message delivery log response.
+   */
+  response: MessageDeliveryLog.Response;
 
-  export namespace MessageInAppFeedContent {
+  /**
+   * The name of the service that processed the delivery.
+   */
+  service_name: string;
+}
+
+export namespace MessageDeliveryLog {
+  /**
+   * A message delivery log request.
+   */
+  export interface Request {
     /**
-     * A block in a message in an app feed.
+     * The body content that was sent with the request.
      */
-    export interface MessageInAppFeedContentBlock {
-      /**
-       * The content of the block in a message in an app feed.
-       */
-      content: string;
+    body?: string | { [key: string]: unknown };
 
-      /**
-       * The name of the block in a message in an app feed.
-       */
-      name: string;
+    /**
+     * The headers that were sent with the request.
+     */
+    headers?: { [key: string]: unknown } | null;
 
-      /**
-       * The rendered HTML version of the content.
-       */
-      rendered: string;
+    /**
+     * The host to which the request was sent.
+     */
+    host?: string;
 
-      /**
-       * The type of block in a message in an app feed.
-       */
-      type: 'markdown' | 'text';
-    }
+    /**
+     * The HTTP method used for the request.
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 
     /**
-     * A button set block in a message in an app feed.
+     * The path of the URL that was requested.
      */
-    export interface MessageInAppFeedButtonSetBlock {
-      /**
-       * A list of buttons in an in app feed message.
-       */
-      buttons: Array<MessageInAppFeedButtonSetBlock.Button>;
+    path?: string;
 
-      /**
-       * The name of the button set in a message in an app feed.
-       */
-      name: string;
+    /**
+     * The query string of the URL that was requested.
+     */
+    query?: string | null;
+  }
 
-      /**
-       * The type of block in a message in an app feed.
-       */
-      type: 'button_set';
-    }
+  /**
+   * A message delivery log response.
+   */
+  export interface Response {
+    /**
+     * The body content that was received with the response.
+     */
+    body?: string | { [key: string]: unknown };
 
-    export namespace MessageInAppFeedButtonSetBlock {
-      /**
-       * A button in an in app feed message.
-       */
-      export interface Button {
-        /**
-         * The action to take when the button is clicked.
-         */
-        action: string;
+    /**
+     * The headers that were received with the response.
+     */
+    headers?: { [key: string]: unknown } | null;
 
-        /**
-         * The label of the button.
-         */
-        label: string;
+    /**
+     * The HTTP status code of the response.
+     */
+    status?: number;
+  }
+}
 
-        /**
-         * The name of the button.
-         */
-        name: string;
-      }
-    }
+/**
+ * A message event. Occurs when a message
+ * [delivery or engagement status](/send-notifications/message-statuses) changes.
+ */
+export interface MessageEvent {
+  /**
+   * The unique identifier for the message event.
+   */
+  id: string;
+
+  /**
+   * The typename of the schema.
+   */
+  __typename: string;
+
+  /**
+   * Timestamp when the event was created.
+   */
+  inserted_at: string;
+
+  /**
+   * A reference to a recipient, either a user identifier (string) or an object
+   * reference (ID, collection).
+   */
+  recipient: RecipientsAPI.RecipientReference;
+
+  /**
+   * The type of event that occurred.
+   */
+  type:
+    | 'message.created'
+    | 'message.queued'
+    | 'message.sent'
+    | 'message.not_sent'
+    | 'message.delivered'
+    | 'message.delivery_attempted'
+    | 'message.undelivered'
+    | 'message.bounced'
+    | 'message.complaint'
+    | 'message.read'
+    | 'message.unread'
+    | 'message.seen'
+    | 'message.unseen'
+    | 'message.archived'
+    | 'message.unarchived'
+    | 'message.interacted'
+    | 'message.link_clicked';
+
+  /**
+   * The data associated with the message event. Only present for some event types.
+   */
+  data?: { [key: string]: unknown } | null;
+}
+
+/**
+ * A button set block in a message in an app feed.
+ */
+export interface MessageInAppFeedButtonSetBlock {
+  /**
+   * A list of buttons in an in app feed message.
+   */
+  buttons: Array<MessageInAppFeedButtonSetBlock.Button>;
+
+  /**
+   * The name of the button set in a message in an app feed.
+   */
+  name: string;
+
+  /**
+   * The type of block in a message in an app feed.
+   */
+  type: 'button_set';
+}
+
+export namespace MessageInAppFeedButtonSetBlock {
+  /**
+   * A button in an in app feed message.
+   */
+  export interface Button {
+    /**
+     * The action to take when the button is clicked.
+     */
+    action: string;
+
+    /**
+     * The label of the button.
+     */
+    label: string;
+
+    /**
+     * The name of the button.
+     */
+    name: string;
   }
 }
 
+/**
+ * A block in a message in an app feed.
+ */
+export interface MessageInAppFeedContentBlock {
+  /**
+   * The content of the block in a message in an app feed.
+   */
+  content: string;
+
+  /**
+   * The name of the block in a message in an app feed.
+   */
+  name: string;
+
+  /**
+   * The rendered HTML version of the content.
+   */
+  rendered: string;
+
+  /**
+   * The type of block in a message in an app feed.
+   */
+  type: 'markdown' | 'text';
+}
+
 export interface MessageListParams extends ItemsCursorParams {
   /**
    * Limits the results to items with the corresponding channel ID.
@@ -1101,10 +1132,13 @@ Messages.Batch = Batch;
 export declare namespace Messages {
   export {
     type Activity as Activity,
+    type ListMessagesResponse as ListMessagesResponse,
     type Message as Message,
+    type MessageContents as MessageContents,
     type MessageDeliveryLog as MessageDeliveryLog,
     type MessageEvent as MessageEvent,
-    type MessageGetContentResponse as MessageGetContentResponse,
+    type MessageInAppFeedButtonSetBlock as MessageInAppFeedButtonSetBlock,
+    type MessageInAppFeedContentBlock as MessageInAppFeedContentBlock,
     type MessagesItemsCursor as MessagesItemsCursor,
     type ActivitiesItemsCursor as ActivitiesItemsCursor,
     type MessageDeliveryLogsItemsCursor as MessageDeliveryLogsItemsCursor,
@@ -1118,6 +1152,7 @@ export declare namespace Messages {
 
   export {
     Batch as Batch,
+    type BatchMessagesStatusRequest as BatchMessagesStatusRequest,
     type BatchArchiveResponse as BatchArchiveResponse,
     type BatchGetContentResponse as BatchGetContentResponse,
     type BatchMarkAsInteractedResponse as BatchMarkAsInteractedResponse,

package/src/resources/objects/objects.ts

@@ -19,6 +19,7 @@ import * as SubscriptionsAPI from '../recipients/subscriptions';
 import { SubscriptionsEntriesCursor } from '../recipients/subscriptions';
 import * as SchedulesAPI from '../schedules/schedules';
 import { SchedulesEntriesCursor } from '../schedules/schedules';
+import * as UsersAPI from '../users/users';
 import { APIPromise } from '../../core/api-promise';
 import {
   EntriesCursor,
@@ -787,9 +788,11 @@ export interface ObjectSetPreferencesParams {
 
   /**
    * Whether the recipient is subscribed to commercial communications. When false,
-   * the recipient will not receive commercial workflow notifications.
+   * the recipient will not receive commercial workflow notifications. Can also be
+   * set to a settings object with conditions that are evaluated at notification send
+   * time.
    */
-  commercial_subscribed?: boolean | null;
+  commercial_subscribed?: boolean | UsersAPI.PreferenceSetCommercialSubscribedSetting | null;
 
   /**
    * An object where the key is the workflow key and the values are the preference

package/src/resources/recipients/channel-data.ts

@@ -213,6 +213,13 @@ export namespace DiscordChannelData {
      * Discord channel ID.
      */
     channel_id: string;
+
+    /**
+     * An optional Knock tenant ID (`knock_tenant_id`) that scopes this connection.
+     * Distinct from provider-specific tenant IDs. When a workflow is triggered with
+     * this tenant, Knock prefers this connection over untagged connections.
+     */
+    knock_tenant_id?: string | null;
   }
 
   /**
@@ -223,6 +230,13 @@ export namespace DiscordChannelData {
      * Discord incoming webhook object.
      */
     incoming_webhook: DiscordIncomingWebhookConnection.IncomingWebhook;
+
+    /**
+     * An optional Knock tenant ID (`knock_tenant_id`) that scopes this connection.
+     * Distinct from provider-specific tenant IDs. When a workflow is triggered with
+     * this tenant, Knock prefers this connection over untagged connections.
+     */
+    knock_tenant_id?: string | null;
   }
 
   export namespace DiscordIncomingWebhookConnection {
@@ -275,6 +289,13 @@ export namespace MsTeamsChannelData {
    * Microsoft Teams token connection.
    */
   export interface MsTeamsTokenConnection {
+    /**
+     * An optional Knock tenant ID (`knock_tenant_id`) that scopes this connection.
+     * Distinct from provider-specific tenant IDs. When a workflow is triggered with
+     * this tenant, Knock prefers this connection over untagged connections.
+     */
+    knock_tenant_id?: string | null;
+
     /**
      * Microsoft Teams channel ID.
      */
@@ -304,6 +325,13 @@ export namespace MsTeamsChannelData {
      * Microsoft Teams incoming webhook.
      */
     incoming_webhook: MsTeamsIncomingWebhookConnection.IncomingWebhook;
+
+    /**
+     * An optional Knock tenant ID (`knock_tenant_id`) that scopes this connection.
+     * Distinct from provider-specific tenant IDs. When a workflow is triggered with
+     * this tenant, Knock prefers this connection over untagged connections.
+     */
+    knock_tenant_id?: string | null;
   }
 
   export namespace MsTeamsIncomingWebhookConnection {
@@ -403,6 +431,18 @@ export namespace SlackChannelData {
      */
     channel_id?: string | null;
 
+    /**
+     * Slack channel name.
+     */
+    channel_name?: string | null;
+
+    /**
+     * An optional Knock tenant ID (`knock_tenant_id`) that scopes this connection.
+     * Distinct from provider-specific tenant IDs. When a workflow is triggered with
+     * this tenant, Knock prefers this connection over untagged connections.
+     */
+    knock_tenant_id?: string | null;
+
     /**
      * A Slack user ID from the Slack provider.
      */
@@ -417,6 +457,13 @@ export namespace SlackChannelData {
      * A Slack connection incoming webhook.
      */
     incoming_webhook: SlackIncomingWebhookConnection.IncomingWebhook;
+
+    /**
+     * An optional Knock tenant ID (`knock_tenant_id`) that scopes this connection.
+     * Distinct from provider-specific tenant IDs. When a workflow is triggered with
+     * this tenant, Knock prefers this connection over untagged connections.
+     */
+    knock_tenant_id?: string | null;
   }
 
   export namespace SlackIncomingWebhookConnection {