@knocklabs/node 1.0.0 → 1.1.0

package/src/resources/audiences.ts

@@ -10,6 +10,18 @@ import { path } from '../internal/utils/path';
 export class Audiences extends APIResource {
   /**
    * Adds one or more members to the specified audience.
+   *
+   * @example
+   * ```ts
+   * const response = await client.audiences.addMembers('key', {
+   *   members: [
+   *     {
+   *       tenant: 'ingen_isla_nublar',
+   *       user: { id: 'dr_sattler' },
+   *     },
+   *   ],
+   * });
+   * ```
    */
   addMembers(key: string, body: AudienceAddMembersParams, options?: RequestOptions): APIPromise<string> {
     return this._client.post(path`/v1/audiences/${key}/members`, { body, ...options });
@@ -17,6 +29,11 @@ export class Audiences extends APIResource {
 
   /**
    * Returns a paginated list of members for the specified audience.
+   *
+   * @example
+   * ```ts
+   * const response = await client.audiences.listMembers('key');
+   * ```
    */
   listMembers(key: string, options?: RequestOptions): APIPromise<AudienceListMembersResponse> {
     return this._client.get(path`/v1/audiences/${key}/members`, options);
@@ -24,6 +41,14 @@ export class Audiences extends APIResource {
 
   /**
    * Removes one or more members from the specified audience.
+   *
+   * @example
+   * ```ts
+   * const response = await client.audiences.removeMembers(
+   *   'key',
+   *   { members: [{ user: {} }] },
+   * );
+   * ```
    */
   removeMembers(
     key: string,
@@ -103,6 +128,9 @@ export namespace AudienceAddMembersParams {
    * An audience member.
    */
   export interface Member {
+    /**
+     * An object containing the user's ID.
+     */
     user: Member.User;
 
     /**
@@ -112,6 +140,9 @@ export namespace AudienceAddMembersParams {
   }
 
   export namespace Member {
+    /**
+     * An object containing the user's ID.
+     */
     export interface User {
       /**
        * The ID for the user that you set when identifying them in Knock.
@@ -133,6 +164,9 @@ export namespace AudienceRemoveMembersParams {
    * An audience member.
    */
   export interface Member {
+    /**
+     * An object containing the user's ID.
+     */
     user: Member.User;
 
     /**
@@ -142,6 +176,9 @@ export namespace AudienceRemoveMembersParams {
   }
 
   export namespace Member {
+    /**
+     * An object containing the user's ID.
+     */
     export interface User {
       /**
        * The ID for the user that you set when identifying them in Knock.

package/src/resources/bulk-operations.ts

@@ -8,6 +8,13 @@ import { path } from '../internal/utils/path';
 export class BulkOperations extends APIResource {
   /**
    * Retrieves a bulk operation (if it exists) and displays the current state of it.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation = await client.bulkOperations.get(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   get(id: string, options?: RequestOptions): APIPromise<BulkOperation> {
     return this._client.get(path`/v1/bulk_operations/${id}`, options);

package/src/resources/channels/bulk.ts

@@ -12,6 +12,27 @@ export class Bulk extends APIResource {
    * specified by the `channel_id` parameter. The action to perform is specified by
    * the `action` parameter, where the action is a status change action (e.g.
    * `archive`, `unarchive`).
+   *
+   * @example
+   * ```ts
+   * const bulkOperation =
+   *   await client.channels.bulk.updateMessageStatus(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *     'seen',
+   *     {
+   *       archived: 'include',
+   *       delivery_status: 'delivered',
+   *       engagement_status: 'seen',
+   *       has_tenant: true,
+   *       newer_than: '2024-01-01T00:00:00Z',
+   *       older_than: '2024-01-01T00:00:00Z',
+   *       recipient_ids: ['recipient1', 'recipient2'],
+   *       tenants: ['tenant1', 'tenant2'],
+   *       trigger_data: '{"key":"value"}',
+   *       workflows: ['workflow1', 'workflow2'],
+   *     },
+   *   );
+   * ```
    */
   updateMessageStatus(
     channelID: string,

package/src/resources/messages/activities.ts

@@ -10,6 +10,16 @@ import { path } from '../../internal/utils/path';
 export class Activities 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.activities.list(
+   *   'message_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     messageID: string,

package/src/resources/messages/batch.ts

@@ -9,6 +9,16 @@ export class Batch extends APIResource {
   /**
    * Marks the given messages as archived. Archived messages are hidden from the
    * default message list in the feed but can still be accessed and unarchived later.
+   *
+   * @example
+   * ```ts
+   * const messages = await client.messages.batch.archive({
+   *   message_ids: [
+   *     '2w3YUpTTOxuDvZFji8OMsKrG176',
+   *     '2w3YVRbPXMIh8Zq6oBFcVDA5xes',
+   *   ],
+   * });
+   * ```
    */
   archive(body: BatchArchiveParams, options?: RequestOptions): APIPromise<BatchArchiveResponse> {
     return this._client.post('/v1/messages/batch/archived', { body, ...options });
@@ -16,6 +26,13 @@ export class Batch extends APIResource {
 
   /**
    * Get the contents of multiple messages in a single request.
+   *
+   * @example
+   * ```ts
+   * const response = await client.messages.batch.getContent({
+   *   message_ids: ['string'],
+   * });
+   * ```
    */
   getContent(query: BatchGetContentParams, options?: RequestOptions): APIPromise<BatchGetContentResponse> {
     return this._client.get('/v1/messages/batch/content', { query, ...options });
@@ -27,6 +44,15 @@ export class Batch extends APIResource {
    * interaction. 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 messages =
+   *   await client.messages.batch.markAsInteracted({
+   *     message_ids: ['1jNaXzB2RZX3LY8wVQnfCKyPnv7'],
+   *     metadata: { key: 'value' },
+   *   });
+   * ```
    */
   markAsInteracted(
     body: BatchMarkAsInteractedParams,
@@ -38,6 +64,16 @@ export class Batch extends APIResource {
   /**
    * Marks the given messages as `read`. Read more about message engagement statuses
    * [here](/send-notifications/message-statuses#engagement-status).
+   *
+   * @example
+   * ```ts
+   * const messages = await client.messages.batch.markAsRead({
+   *   message_ids: [
+   *     '2w3YUpTTOxuDvZFji8OMsKrG176',
+   *     '2w3YVRbPXMIh8Zq6oBFcVDA5xes',
+   *   ],
+   * });
+   * ```
    */
   markAsRead(body: BatchMarkAsReadParams, options?: RequestOptions): APIPromise<BatchMarkAsReadResponse> {
     return this._client.post('/v1/messages/batch/read', { body, ...options });
@@ -47,6 +83,16 @@ export class Batch extends APIResource {
    * Marks the given messages 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 messages = await client.messages.batch.markAsSeen({
+   *   message_ids: [
+   *     '2w3YUpTTOxuDvZFji8OMsKrG176',
+   *     '2w3YVRbPXMIh8Zq6oBFcVDA5xes',
+   *   ],
+   * });
+   * ```
    */
   markAsSeen(body: BatchMarkAsSeenParams, options?: RequestOptions): APIPromise<BatchMarkAsSeenResponse> {
     return this._client.post('/v1/messages/batch/seen', { body, ...options });
@@ -56,6 +102,16 @@ export class Batch extends APIResource {
    * Marks the given messages as `unread`. This reverses the `read` state. Read more
    * about message engagement statuses
    * [here](/send-notifications/message-statuses#engagement-status).
+   *
+   * @example
+   * ```ts
+   * const messages = await client.messages.batch.markAsUnread({
+   *   message_ids: [
+   *     '2w3YUpTTOxuDvZFji8OMsKrG176',
+   *     '2w3YVRbPXMIh8Zq6oBFcVDA5xes',
+   *   ],
+   * });
+   * ```
    */
   markAsUnread(
     body: BatchMarkAsUnreadParams,
@@ -68,6 +124,16 @@ export class Batch extends APIResource {
    * Marks the given messages as `unseen`. This reverses the `seen` state. Read more
    * about message engagement statuses
    * [here](/send-notifications/message-statuses#engagement-status).
+   *
+   * @example
+   * ```ts
+   * const messages = await client.messages.batch.markAsUnseen({
+   *   message_ids: [
+   *     '2w3YUpTTOxuDvZFji8OMsKrG176',
+   *     '2w3YVRbPXMIh8Zq6oBFcVDA5xes',
+   *   ],
+   * });
+   * ```
    */
   markAsUnseen(
     body: BatchMarkAsUnseenParams,
@@ -80,6 +146,16 @@ export class Batch extends APIResource {
    * Marks the given messages as unarchived. This reverses the `archived` state.
    * Archived messages are hidden from the default message list in the feed but can
    * still be accessed and unarchived later.
+   *
+   * @example
+   * ```ts
+   * const messages = await client.messages.batch.unarchive({
+   *   message_ids: [
+   *     '2w3YUpTTOxuDvZFji8OMsKrG176',
+   *     '2w3YVRbPXMIh8Zq6oBFcVDA5xes',
+   *   ],
+   * });
+   * ```
    */
   unarchive(body: BatchUnarchiveParams, options?: RequestOptions): APIPromise<BatchUnarchiveResponse> {
     return this._client.post('/v1/messages/batch/unarchived', { body, ...options });

package/src/resources/messages/messages.ts

@@ -41,6 +41,14 @@ export class Messages extends APIResource {
 
   /**
    * 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 +60,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 +74,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 +89,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 +103,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 +127,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 +152,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 +180,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 +200,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 +216,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 +232,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 +248,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 +263,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);

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,