@knocklabs/node 1.0.0 → 1.2.0

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 });
@@ -177,8 +251,7 @@ export type ScheduleDeleteResponse = Array<Schedule>;
 
 export interface ScheduleCreateParams {
   /**
-   * The recipients to trigger the workflow for. Can inline identify users, objects,
-   * or use a list of user IDs. Limited to 1,000 recipients.
+   * The recipients to set the schedule for. Limited to 100 recipients per request.
    */
   recipients: Array<RecipientsAPI.RecipientRequest>;
 

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,

package/src/resources/users/feeds.ts

@@ -11,6 +11,14 @@ import { path } from '../../internal/utils/path';
 export class Feeds extends APIResource {
   /**
    * Returns the feed settings for a user.
+   *
+   * @example
+   * ```ts
+   * const response = await client.users.feeds.getSettings(
+   *   'user_id',
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   getSettings(userID: string, id: string, options?: RequestOptions): APIPromise<FeedGetSettingsResponse> {
     return this._client.get(path`/v1/users/${userID}/feeds/${id}/settings`, options);
@@ -19,6 +27,17 @@ export class Feeds extends APIResource {
   /**
    * Returns a paginated list of feed items for a user, including metadata about the
    * feed.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const feedListItemsResponse of client.users.feeds.listItems(
+   *   'user_id',
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listItems(
     userID: string,

package/src/resources/users/guides.ts

@@ -8,6 +8,14 @@ import { path } from '../../internal/utils/path';
 export class Guides extends APIResource {
   /**
    * Returns a list of eligible in-app guides for a specific user and channel.
+   *
+   * @example
+   * ```ts
+   * const response = await client.users.guides.getChannel(
+   *   'user_id',
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   getChannel(
     userID: string,
@@ -21,6 +29,21 @@ export class Guides extends APIResource {
   /**
    * Records that a guide has been archived by a user, triggering any associated
    * archived events.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.users.guides.markMessageAsArchived(
+   *     'user_id',
+   *     'message_id',
+   *     {
+   *       channel_id: '123e4567-e89b-12d3-a456-426614174000',
+   *       guide_id: '7e9dc78c-b3b1-4127-a54e-71f1899b831a',
+   *       guide_key: 'tour_notification',
+   *       guide_step_ref: 'lab_tours',
+   *     },
+   *   );
+   * ```
    */
   markMessageAsArchived(
     userID: string,
@@ -37,6 +60,21 @@ export class Guides extends APIResource {
   /**
    * Records that a user has interacted with a guide, triggering any associated
    * interacted events.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.users.guides.markMessageAsInteracted(
+   *     'user_id',
+   *     'message_id',
+   *     {
+   *       channel_id: '123e4567-e89b-12d3-a456-426614174000',
+   *       guide_id: '7e9dc78c-b3b1-4127-a54e-71f1899b831a',
+   *       guide_key: 'tour_notification',
+   *       guide_step_ref: 'lab_tours',
+   *     },
+   *   );
+   * ```
    */
   markMessageAsInteracted(
     userID: string,
@@ -53,6 +91,36 @@ export class Guides extends APIResource {
   /**
    * Records that a guide has been seen by a user, triggering any associated seen
    * events.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.users.guides.markMessageAsSeen(
+   *     'user_id',
+   *     'message_id',
+   *     {
+   *       channel_id: '123e4567-e89b-12d3-a456-426614174000',
+   *       guide_id: '7e9dc78c-b3b1-4127-a54e-71f1899b831a',
+   *       guide_key: 'tour_notification',
+   *       guide_step_ref: 'lab_tours',
+   *       content: {
+   *         body: "Limited spots available for today's behind-the-scenes DNA extraction demonstration.",
+   *         title: 'DNA Lab Tour Available',
+   *       },
+   *       data: {
+   *         next_time: '14:30',
+   *         spots_left: 8,
+   *         tour_id: 'dna_lab_tour',
+   *       },
+   *       metadata: {
+   *         cta: 'Reserve Spot',
+   *         theme: 'amber',
+   *         type: 'banner',
+   *       },
+   *       tenant: 'ingen_isla_nublar',
+   *     },
+   *   );
+   * ```
    */
   markMessageAsSeen(
     userID: string,