@knocklabs/node 1.0.0 → 1.1.0

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': {
+   *         data: { 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,
@@ -508,10 +679,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/schedules/bulk.ts

@@ -13,6 +13,36 @@ export class Bulk extends APIResource {
    * Bulk creates up to 1,000 schedules at a time. This endpoint also handles
    * [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients)
    * for the `actor`, `recipient`, and `tenant` fields.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation = await client.schedules.bulk.create({
+   *   schedules: [
+   *     {
+   *       data: { ... },
+   *       ending_at: null,
+   *       recipient: 'dnedry',
+   *       repeats: [
+   *         { ... },
+   *       ],
+   *       scheduled_at: null,
+   *       tenant: 'acme_corp',
+   *       workflow: 'comment-created',
+   *     },
+   *     {
+   *       data: { ... },
+   *       ending_at: null,
+   *       recipient: 'esattler',
+   *       repeats: [
+   *         { ... },
+   *       ],
+   *       scheduled_at: null,
+   *       tenant: 'acme_corp',
+   *       workflow: 'comment-created',
+   *     },
+   *   ],
+   * });
+   * ```
    */
   create(body: BulkCreateParams, options?: RequestOptions): APIPromise<BulkOperationsAPI.BulkOperation> {
     return this._client.post('/v1/schedules/bulk/create', { body, ...options });

package/src/resources/schedules/schedules.ts

@@ -18,6 +18,35 @@ export class Schedules extends APIResource {
    * handles
    * [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients)
    * for the `actor`, `recipient`, and `tenant` fields.
+   *
+   * @example
+   * ```ts
+   * const schedules = await client.schedules.create({
+   *   recipients: ['user_123'],
+   *   repeats: [
+   *     {
+   *       __typename: 'ScheduleRepeat',
+   *       day_of_month: null,
+   *       days: [
+   *         'mon',
+   *         'tue',
+   *         'wed',
+   *         'thu',
+   *         'fri',
+   *         'sat',
+   *         'sun',
+   *       ],
+   *       frequency: 'daily',
+   *       hours: null,
+   *       interval: 1,
+   *       minutes: null,
+   *     },
+   *   ],
+   *   workflow: 'comment-created',
+   *   data: { key: 'value' },
+   *   tenant: 'acme_corp',
+   * });
+   * ```
    */
   create(body: ScheduleCreateParams, options?: RequestOptions): APIPromise<ScheduleCreateResponse> {
     return this._client.post('/v1/schedules', { body, ...options });
@@ -29,6 +58,34 @@ export class Schedules extends APIResource {
    * This endpoint also handles
    * [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients)
    * for the `actor`, `recipient`, and `tenant` fields.
+   *
+   * @example
+   * ```ts
+   * const schedules = await client.schedules.update({
+   *   schedule_ids: ['123e4567-e89b-12d3-a456-426614174000'],
+   *   data: { key: 'value' },
+   *   repeats: [
+   *     {
+   *       __typename: 'ScheduleRepeat',
+   *       day_of_month: null,
+   *       days: [
+   *         'mon',
+   *         'tue',
+   *         'wed',
+   *         'thu',
+   *         'fri',
+   *         'sat',
+   *         'sun',
+   *       ],
+   *       frequency: 'daily',
+   *       hours: null,
+   *       interval: 1,
+   *       minutes: null,
+   *     },
+   *   ],
+   *   tenant: 'acme_corp',
+   * });
+   * ```
    */
   update(body: ScheduleUpdateParams, options?: RequestOptions): APIPromise<ScheduleUpdateResponse> {
     return this._client.put('/v1/schedules', { body, ...options });
@@ -37,6 +94,16 @@ export class Schedules extends APIResource {
   /**
    * Returns a paginated list of schedules for the current environment, filtered by
    * workflow and optionally by recipients and tenant.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const schedule of client.schedules.list({
+   *   workflow: 'workflow',
+   * })) {
+   *   // ...
+   * }
+   * ```
    */
   list(query: ScheduleListParams, options?: RequestOptions): PagePromise<SchedulesEntriesCursor, Schedule> {
     return this._client.getAPIList('/v1/schedules', EntriesCursor<Schedule>, { query, ...options });
@@ -45,6 +112,13 @@ export class Schedules extends APIResource {
   /**
    * Permanently deletes one or more schedules identified by the provided schedule
    * IDs. This operation cannot be undone.
+   *
+   * @example
+   * ```ts
+   * const schedules = await client.schedules.delete({
+   *   schedule_ids: ['123e4567-e89b-12d3-a456-426614174000'],
+   * });
+   * ```
    */
   delete(body: ScheduleDeleteParams, options?: RequestOptions): APIPromise<ScheduleDeleteResponse> {
     return this._client.delete('/v1/schedules', { body, ...options });

package/src/resources/tenants/bulk.ts

@@ -9,6 +9,13 @@ import { RequestOptions } from '../../internal/request-options';
 export class Bulk extends APIResource {
   /**
    * Delete multiple tenants in a single operation. This operation cannot be undone.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation = await client.tenants.bulk.delete({
+   *   tenant_ids: ['string'],
+   * });
+   * ```
    */
   delete(params: BulkDeleteParams, options?: RequestOptions): APIPromise<BulkOperationsAPI.BulkOperation> {
     const { tenant_ids } = params;
@@ -17,6 +24,13 @@ export class Bulk extends APIResource {
 
   /**
    * Set or update up to 1,000 tenants in a single operation.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation = await client.tenants.bulk.set({
+   *   tenants: ['[object Object]'],
+   * });
+   * ```
    */
   set(body: BulkSetParams, options?: RequestOptions): APIPromise<BulkOperationsAPI.BulkOperation> {
     return this._client.post('/v1/tenants/bulk/set', { body, ...options });

package/src/resources/tenants/tenants.ts

@@ -15,6 +15,14 @@ export class Tenants extends APIResource {
 
   /**
    * List tenants for the current environment.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const tenant of client.tenants.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: TenantListParams | null | undefined = {},
@@ -25,6 +33,11 @@ export class Tenants extends APIResource {
 
   /**
    * Delete a tenant and all associated data. This operation cannot be undone.
+   *
+   * @example
+   * ```ts
+   * const tenant = await client.tenants.delete('id');
+   * ```
    */
   delete(id: string, options?: RequestOptions): APIPromise<string> {
     return this._client.delete(path`/v1/tenants/${id}`, options);
@@ -32,6 +45,11 @@ export class Tenants extends APIResource {
 
   /**
    * Get a tenant by ID.
+   *
+   * @example
+   * ```ts
+   * const tenant = await client.tenants.get('id');
+   * ```
    */
   get(id: string, options?: RequestOptions): APIPromise<Tenant> {
     return this._client.get(path`/v1/tenants/${id}`, options);
@@ -40,6 +58,21 @@ export class Tenants extends APIResource {
   /**
    * Sets a tenant within an environment, performing an upsert operation. Any
    * existing properties will be merged with the incoming properties.
+   *
+   * @example
+   * ```ts
+   * const tenant = await client.tenants.set('id', {
+   *   settings: {
+   *     branding: {
+   *       icon_url:
+   *         'https://example.com/trex_silhouette_icon.png',
+   *       logo_url: 'https://example.com/amber_fossil_logo.png',
+   *       primary_color: '#DF1A22',
+   *       primary_color_contrast: '#FFDE00',
+   *     },
+   *   },
+   * });
+   * ```
    */
   set(id: string, body: TenantSetParams, options?: RequestOptions): APIPromise<Tenant> {
     return this._client.put(path`/v1/tenants/${id}`, { body, ...options });

package/src/resources/users/bulk.ts

@@ -11,6 +11,13 @@ export class Bulk extends APIResource {
   /**
    * Deletes multiple users in a single operation. Accepts up to 100 user IDs to
    * delete and returns a bulk operation that can be queried for progress.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation = await client.users.bulk.delete({
+   *   user_ids: ['user_1', 'user_2'],
+   * });
+   * ```
    */
   delete(body: BulkDeleteParams, options?: RequestOptions): APIPromise<BulkOperationsAPI.BulkOperation> {
     return this._client.post('/v1/users/bulk/delete', { body, ...options });
@@ -20,6 +27,20 @@ export class Bulk extends APIResource {
    * Identifies multiple users in a single operation. Allows creating or updating up
    * to 100 users in a single batch with various properties, preferences, and channel
    * data.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation = await client.users.bulk.identify({
+   *   users: [
+   *     {
+   *       email: 'jane@ingen.net',
+   *       id: 'user_1',
+   *       name: 'Jane Doe',
+   *       timezone: 'America/New_York',
+   *     },
+   *   ],
+   * });
+   * ```
    */
   identify(body: BulkIdentifyParams, options?: RequestOptions): APIPromise<BulkOperationsAPI.BulkOperation> {
     return this._client.post('/v1/users/bulk/identify', { body, ...options });
@@ -29,6 +50,26 @@ export class Bulk extends APIResource {
    * Sets preferences for multiple users in a single operation. Supports either
    * setting the same preferences for multiple users or specific preferences for each
    * user.
+   *
+   * @example
+   * ```ts
+   * const bulkOperation =
+   *   await client.users.bulk.setPreferences({
+   *     preferences: {
+   *       categories: {
+   *         marketing: false,
+   *         transactional: { channel_types: { email: false } },
+   *       },
+   *       channel_types: { email: true },
+   *       workflows: {
+   *         'dinosaurs-loose': {
+   *           channel_types: { email: false },
+   *         },
+   *       },
+   *     },
+   *     user_ids: ['user_1', 'user_2'],
+   *   });
+   * ```
    */
   setPreferences(
     body: BulkSetPreferencesParams,