@knocklabs/node 1.0.0 → 1.2.0

package/src/resources/messages/messages.ts

@@ -1,8 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
-import * as ActivitiesAPI from './activities';
-import { Activities, ActivityListParams } from './activities';
 import * as BatchAPI from './batch';
 import {
   Batch,
@@ -37,10 +35,17 @@ import { path } from '../../internal/utils/path';
 
 export class Messages extends APIResource {
   batch: BatchAPI.Batch = new BatchAPI.Batch(this._client);
-  activities: ActivitiesAPI.Activities = new ActivitiesAPI.Activities(this._client);
 
   /**
    * Returns a paginated list of messages for the current environment.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const message of client.messages.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: MessageListParams | null | undefined = {},
@@ -52,6 +57,13 @@ export class Messages extends APIResource {
   /**
    * Archives a message for the user. Archived messages are hidden from the default
    * message list in the feed but can still be accessed and unarchived later.
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.archive(
+   *   '1jNaXzB2RZX3LY8wVQnfCKyPnv7',
+   * );
+   * ```
    */
   archive(messageID: string, options?: RequestOptions): APIPromise<Message> {
     return this._client.put(path`/v1/messages/${messageID}/archived`, options);
@@ -59,6 +71,13 @@ export class Messages extends APIResource {
 
   /**
    * Retrieves a specific message by its ID.
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.get(
+   *   '1jNaXzB2RZX3LY8wVQnfCKyPnv7',
+   * );
+   * ```
    */
   get(messageID: string, options?: RequestOptions): APIPromise<Message> {
     return this._client.get(path`/v1/messages/${messageID}`, options);
@@ -67,6 +86,13 @@ export class Messages extends APIResource {
   /**
    * Returns the fully rendered contents of a message, where the response depends on
    * which channel the message was sent through.
+   *
+   * @example
+   * ```ts
+   * const response = await client.messages.getContent(
+   *   'message_id',
+   * );
+   * ```
    */
   getContent(messageID: string, options?: RequestOptions): APIPromise<MessageGetContentResponse> {
     return this._client.get(path`/v1/messages/${messageID}/content`, options);
@@ -74,6 +100,16 @@ export class Messages extends APIResource {
 
   /**
    * Returns a paginated list of activities for the specified message.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const activity of client.messages.listActivities(
+   *   'message_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listActivities(
     messageID: string,
@@ -88,6 +124,16 @@ export class Messages extends APIResource {
 
   /**
    * Returns a paginated list of delivery logs for the specified message.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const messageDeliveryLog of client.messages.listDeliveryLogs(
+   *   'message_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listDeliveryLogs(
     messageID: string,
@@ -103,6 +149,16 @@ export class Messages extends APIResource {
 
   /**
    * Returns a paginated list of events for the specified message.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const messageEvent of client.messages.listEvents(
+   *   'message_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listEvents(
     messageID: string,
@@ -121,6 +177,13 @@ export class Messages extends APIResource {
    * Cannot include more than 5 key-value pairs, must not contain nested data. Read
    * more about message engagement statuses
    * [here](/send-notifications/message-statuses#engagement-status).
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.markAsInteracted(
+   *   '1jNaXzB2RZX3LY8wVQnfCKyPnv7',
+   * );
+   * ```
    */
   markAsInteracted(
     messageID: string,
@@ -134,6 +197,13 @@ export class Messages extends APIResource {
    * Marks a message as `read`. This indicates that the user has read the message
    * content. Read more about message engagement statuses
    * [here](/send-notifications/message-statuses#engagement-status).
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.markAsRead(
+   *   '1jNaXzB2RZX3LY8wVQnfCKyPnv7',
+   * );
+   * ```
    */
   markAsRead(messageID: string, options?: RequestOptions): APIPromise<Message> {
     return this._client.put(path`/v1/messages/${messageID}/read`, options);
@@ -143,6 +213,13 @@ export class Messages extends APIResource {
    * Marks a message as `seen`. This indicates that the user has viewed the message
    * in their feed or inbox. Read more about message engagement statuses
    * [here](/send-notifications/message-statuses#engagement-status).
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.markAsSeen(
+   *   '1jNaXzB2RZX3LY8wVQnfCKyPnv7',
+   * );
+   * ```
    */
   markAsSeen(messageID: string, options?: RequestOptions): APIPromise<Message> {
     return this._client.put(path`/v1/messages/${messageID}/seen`, options);
@@ -152,6 +229,13 @@ export class Messages extends APIResource {
    * Marks a message as `unread`. This reverses the `read` state. Read more about
    * message engagement statuses
    * [here](/send-notifications/message-statuses#engagement-status).
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.markAsUnread(
+   *   '1jNaXzB2RZX3LY8wVQnfCKyPnv7',
+   * );
+   * ```
    */
   markAsUnread(messageID: string, options?: RequestOptions): APIPromise<Message> {
     return this._client.delete(path`/v1/messages/${messageID}/read`, options);
@@ -161,6 +245,13 @@ export class Messages extends APIResource {
    * Marks a message as `unseen`. This reverses the `seen` state. Read more about
    * message engagement statuses
    * [here](/send-notifications/message-statuses#engagement-status).
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.markAsUnseen(
+   *   '1jNaXzB2RZX3LY8wVQnfCKyPnv7',
+   * );
+   * ```
    */
   markAsUnseen(messageID: string, options?: RequestOptions): APIPromise<Message> {
     return this._client.delete(path`/v1/messages/${messageID}/seen`, options);
@@ -169,6 +260,13 @@ export class Messages extends APIResource {
   /**
    * Removes a message from the archived state, making it visible in the default
    * message list in the feed again.
+   *
+   * @example
+   * ```ts
+   * const message = await client.messages.unarchive(
+   *   '1jNaXzB2RZX3LY8wVQnfCKyPnv7',
+   * );
+   * ```
    */
   unarchive(messageID: string, options?: RequestOptions): APIPromise<Message> {
     return this._client.delete(path`/v1/messages/${messageID}/archived`, options);
@@ -910,7 +1008,6 @@ export interface MessageMarkAsInteractedParams {
 }
 
 Messages.Batch = Batch;
-Messages.Activities = Activities;
 
 export declare namespace Messages {
   export {
@@ -949,6 +1046,4 @@ export declare namespace Messages {
     type BatchMarkAsUnseenParams as BatchMarkAsUnseenParams,
     type BatchUnarchiveParams as BatchUnarchiveParams,
   };
-
-  export { Activities as Activities, type ActivityListParams as ActivityListParams };
 }

package/src/resources/objects/bulk.ts

@@ -11,6 +11,14 @@ import { path } from '../../internal/utils/path';
 export class Bulk extends APIResource {
   /**
    * Bulk deletes objects from the specified collection.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation = await client.objects.bulk.delete(
+   *   'collection',
+   *   { object_ids: ['obj_123', 'obj_456', 'obj_789'] },
+   * );
+   * ```
    */
   delete(
     collection: string,
@@ -26,6 +34,20 @@ export class Bulk extends APIResource {
    * also handles
    * [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients)
    * for the `recipient` field.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation =
+   *   await client.objects.bulk.addSubscriptions('projects', {
+   *     subscriptions: [
+   *       {
+   *         id: 'project-1',
+   *         properties: null,
+   *         recipients: [{ id: 'user_1' }],
+   *       },
+   *     ],
+   *   });
+   * ```
    */
   addSubscriptions(
     collection: string,
@@ -37,6 +59,33 @@ export class Bulk extends APIResource {
 
   /**
    * Bulk sets up to 1,000 objects at a time in the specified collection.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation = await client.objects.bulk.set(
+   *   'collection',
+   *   {
+   *     objects: [
+   *       {
+   *         collection: 'projects',
+   *         id: 'project_1',
+   *         name: {
+   *           '0': 'M',
+   *           '1': 'y',
+   *           '2': ' ',
+   *           '3': 'p',
+   *           '4': 'r',
+   *           '5': 'o',
+   *           '6': 'j',
+   *           '7': 'e',
+   *           '8': 'c',
+   *           '9': 't',
+   *         },
+   *       },
+   *     ],
+   *   },
+   * );
+   * ```
    */
   set(
     collection: string,

package/src/resources/objects/objects.ts

@@ -24,6 +24,16 @@ export class Objects extends APIResource {
   /**
    * Returns a paginated list of objects from the specified collection. Optionally
    * includes preference data for the objects.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const object of client.objects.list(
+   *   'collection',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     collection: string,
@@ -39,6 +49,14 @@ export class Objects extends APIResource {
   /**
    * Permanently removes an object from the specified collection. This operation
    * cannot be undone.
+   *
+   * @example
+   * ```ts
+   * const object = await client.objects.delete(
+   *   'collection',
+   *   'id',
+   * );
+   * ```
    */
   delete(collection: string, id: string, options?: RequestOptions): APIPromise<string> {
     return this._client.delete(path`/v1/objects/${collection}/${id}`, options);
@@ -49,6 +67,18 @@ export class Objects extends APIResource {
    * updated. This endpoint also handles
    * [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients)
    * for the `recipient`.
+   *
+   * @example
+   * ```ts
+   * const subscriptions = await client.objects.addSubscriptions(
+   *   'collection',
+   *   'object_id',
+   *   {
+   *     recipients: ['user_1', 'user_2'],
+   *     properties: { key: 'value' },
+   *   },
+   * );
+   * ```
    */
   addSubscriptions(
     collection: string,
@@ -62,6 +92,16 @@ export class Objects extends APIResource {
   /**
    * Delete subscriptions for the specified recipients from an object. Returns the
    * list of deleted subscriptions.
+   *
+   * @example
+   * ```ts
+   * const subscriptions =
+   *   await client.objects.deleteSubscriptions(
+   *     'collection',
+   *     'object_id',
+   *     { recipients: ['user_123'] },
+   *   );
+   * ```
    */
   deleteSubscriptions(
     collection: string,
@@ -78,6 +118,11 @@ export class Objects extends APIResource {
   /**
    * Retrieves a specific object by its ID from the specified collection. Returns the
    * object with all its properties.
+   *
+   * @example
+   * ```ts
+   * const object = await client.objects.get('collection', 'id');
+   * ```
    */
   get(collection: string, id: string, options?: RequestOptions): APIPromise<Object> {
     return this._client.get(path`/v1/objects/${collection}/${id}`, options);
@@ -85,6 +130,15 @@ export class Objects extends APIResource {
 
   /**
    * Returns the channel data for the specified object and channel.
+   *
+   * @example
+   * ```ts
+   * const channelData = await client.objects.getChannelData(
+   *   'collection',
+   *   'object_id',
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   getChannelData(
     collection: string,
@@ -97,6 +151,15 @@ export class Objects extends APIResource {
 
   /**
    * Returns the preference set for the specified object and preference set `id`.
+   *
+   * @example
+   * ```ts
+   * const preferenceSet = await client.objects.getPreferences(
+   *   'collection',
+   *   'object_id',
+   *   'default',
+   * );
+   * ```
    */
   getPreferences(
     collection: string,
@@ -111,6 +174,17 @@ export class Objects extends APIResource {
    * Returns a paginated list of messages for a specific object in the given
    * collection. Allows filtering by message status and provides various sorting
    * options.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const message of client.objects.listMessages(
+   *   'projects',
+   *   'project-123',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listMessages(
     collection: string,
@@ -127,6 +201,14 @@ export class Objects extends APIResource {
 
   /**
    * Returns a paginated list of preference sets for the specified object.
+   *
+   * @example
+   * ```ts
+   * const preferenceSets = await client.objects.listPreferences(
+   *   'collection',
+   *   'object_id',
+   * );
+   * ```
    */
   listPreferences(
     collection: string,
@@ -138,6 +220,17 @@ export class Objects extends APIResource {
 
   /**
    * Returns a paginated list of schedules for an object.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const schedule of client.objects.listSchedules(
+   *   'collection',
+   *   'id',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listSchedules(
     collection: string,
@@ -156,6 +249,17 @@ export class Objects extends APIResource {
    * List subscriptions for an object. Either list the recipients that subscribe to
    * the provided object, or list the objects that the provided object is subscribed
    * to. Determined by the `mode` query parameter.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const subscription of client.objects.listSubscriptions(
+   *   'collection',
+   *   'object_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listSubscriptions(
     collection: string,
@@ -174,6 +278,33 @@ export class Objects extends APIResource {
    * Creates a new object or updates an existing one in the specified collection.
    * This operation is used to identify objects with their properties, as well as
    * optional preferences and channel data.
+   *
+   * @example
+   * ```ts
+   * const object = await client.objects.set(
+   *   'collection',
+   *   'id',
+   *   {
+   *     channel_data: {
+   *       '97c5837d-c65c-4d54-aa39-080eeb81c69d': {
+   *         tokens: ['push_token_123'],
+   *       },
+   *     },
+   *     locale: 'en-US',
+   *     preferences: {
+   *       default: {
+   *         channel_types: { email: true },
+   *         workflows: {
+   *           'dinosaurs-loose': {
+   *             channel_types: { email: true },
+   *           },
+   *         },
+   *       },
+   *     },
+   *     timezone: 'America/New_York',
+   *   },
+   * );
+   * ```
    */
   set(collection: string, id: string, body: ObjectSetParams, options?: RequestOptions): APIPromise<Object> {
     return this._client.put(path`/v1/objects/${collection}/${id}`, { body, ...options });
@@ -183,6 +314,16 @@ export class Objects extends APIResource {
    * Sets the channel data for the specified object and channel. If no object exists
    * in the current environment for the given `collection` and `object_id`, Knock
    * will create the object as part of this request.
+   *
+   * @example
+   * ```ts
+   * const channelData = await client.objects.setChannelData(
+   *   'collection',
+   *   'object_id',
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   { data: { tokens: ['push_token_1'] } },
+   * );
+   * ```
    */
   setChannelData(
     collection: string,
@@ -204,6 +345,27 @@ export class Objects extends APIResource {
    * `:object_id`, Knock will create the object as part of this request. The
    * preference set `:id` can be either `default` or a `tenant.id`. Learn more about
    * [per-tenant preferences](/preferences/tenant-preferences).
+   *
+   * @example
+   * ```ts
+   * const preferenceSet = await client.objects.setPreferences(
+   *   'collection',
+   *   'object_id',
+   *   'default',
+   *   {
+   *     categories: {
+   *       marketing: false,
+   *       transactional: { channel_types: { email: false } },
+   *     },
+   *     channel_types: { email: true },
+   *     workflows: {
+   *       'dinosaurs-loose': {
+   *         channel_types: { email: false },
+   *       },
+   *     },
+   *   },
+   * );
+   * ```
    */
   setPreferences(
     collection: string,
@@ -220,6 +382,15 @@ export class Objects extends APIResource {
 
   /**
    * Unsets the channel data for the specified object and channel.
+   *
+   * @example
+   * ```ts
+   * const response = await client.objects.unsetChannelData(
+   *   'collection',
+   *   'object_id',
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   unsetChannelData(
     collection: string,
@@ -297,7 +468,10 @@ export interface Object {
    */
   created_at?: string | null;
 
-  [k: string]: unknown;
+  /**
+   * The custom properties associated with the object.
+   */
+  properties?: Record<string, unknown>;
 }
 
 /**
@@ -508,10 +682,10 @@ export interface ObjectSetParams {
   preferences?: PreferencesAPI.InlinePreferenceSetRequest;
 
   /**
-   * The timezone of the object. Must be a valid
-   * [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
-   * Used for
-   * [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients).
+   * The timezone of the object. Must be a
+   * valid [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+   * Used
+   * for [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients).
    */
   timezone?: string | null;
 

package/src/resources/providers/ms-teams.ts

@@ -10,6 +10,14 @@ export class MsTeams extends APIResource {
   /**
    * Check if a connection to Microsoft Teams has been authorized for a given
    * Microsoft Teams tenant object.
+   *
+   * @example
+   * ```ts
+   * const response = await client.providers.msTeams.checkAuth(
+   *   'channel_id',
+   *   { ms_teams_tenant_object: 'ms_teams_tenant_object' },
+   * );
+   * ```
    */
   checkAuth(
     channelID: string,
@@ -22,6 +30,18 @@ export class MsTeams extends APIResource {
   /**
    * List the Microsoft Teams channels within a team. By default, archived and
    * private channels are excluded from the results.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.providers.msTeams.listChannels(
+   *     'channel_id',
+   *     {
+   *       ms_teams_tenant_object: 'ms_teams_tenant_object',
+   *       team_id: 'team_id',
+   *     },
+   *   );
+   * ```
    */
   listChannels(
     channelID: string,
@@ -34,6 +54,17 @@ export class MsTeams extends APIResource {
   /**
    * Get a list of teams belonging to the Microsoft Entra tenant. By default,
    * archived and private channels are excluded from the results.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const msTeamListTeamsResponse of client.providers.msTeams.listTeams(
+   *   'channel_id',
+   *   { ms_teams_tenant_object: 'ms_teams_tenant_object' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listTeams(
     channelID: string,
@@ -49,6 +80,15 @@ export class MsTeams extends APIResource {
 
   /**
    * Remove a Microsoft Entra tenant ID from a Microsoft Teams tenant object.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.providers.msTeams.revokeAccess(
+   *     'channel_id',
+   *     { ms_teams_tenant_object: 'ms_teams_tenant_object' },
+   *   );
+   * ```
    */
   revokeAccess(
     channelID: string,

package/src/resources/providers/slack.ts

@@ -9,6 +9,14 @@ import { path } from '../../internal/utils/path';
 export class Slack extends APIResource {
   /**
    * Check if a Slack channel is authenticated.
+   *
+   * @example
+   * ```ts
+   * const response = await client.providers.slack.checkAuth(
+   *   'channel_id',
+   *   { access_token_object: 'access_token_object' },
+   * );
+   * ```
    */
   checkAuth(
     channelID: string,
@@ -20,6 +28,17 @@ export class Slack extends APIResource {
 
   /**
    * List Slack channels for a Slack workspace.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const slackListChannelsResponse of client.providers.slack.listChannels(
+   *   'channel_id',
+   *   { access_token_object: 'access_token_object' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listChannels(
     channelID: string,
@@ -35,6 +54,14 @@ export class Slack extends APIResource {
 
   /**
    * Revoke access for a Slack channel.
+   *
+   * @example
+   * ```ts
+   * const response = await client.providers.slack.revokeAccess(
+   *   'channel_id',
+   *   { access_token_object: 'access_token_object' },
+   * );
+   * ```
    */
   revokeAccess(
     channelID: string,

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

@@ -96,7 +96,10 @@ export namespace DiscordChannelData {
 /**
  * A request to set channel data for a type of channel inline.
  */
-export type InlineChannelDataRequest = Record<string, ChannelDataRequest>;
+export type InlineChannelDataRequest = Record<
+  string,
+  PushChannelData | OneSignalChannelData | SlackChannelData | MsTeamsChannelData | DiscordChannelData
+>;
 
 /**
  * Microsoft Teams channel connection.