@knocklabs/node 1.29.1 → 1.31.0

package/src/resources/messages/batch.ts

@@ -5,6 +5,9 @@ import * as MessagesAPI from './messages';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * A message sent to a single recipient on a channel.
+ */
 export class Batch extends APIResource {
   /**
    * Marks the given messages as archived. Archived messages are hidden from the

package/src/resources/messages/messages.ts

@@ -27,6 +27,9 @@ import { ItemsCursor, type ItemsCursorParams, PagePromise } from '../../core/pag
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * A message sent to a single recipient on a channel.
+ */
 export class Messages extends APIResource {
   batch: BatchAPI.Batch = new BatchAPI.Batch(this._client);
 
@@ -658,6 +661,7 @@ export interface MessageEvent {
   type:
     | 'message.archived'
     | 'message.bounced'
+    | 'message.created'
     | 'message.delivered'
     | 'message.delivery_attempted'
     | 'message.interacted'

package/src/resources/objects/bulk.ts

@@ -9,6 +9,9 @@ import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * A bulk operation is a set of changes applied across zero or more records triggered via a call to the Knock API and performed asynchronously.
+ */
 export class Bulk extends APIResource {
   /**
    * Bulk deletes objects from the specified collection.

package/src/resources/objects/objects.ts

@@ -31,6 +31,9 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * An object represents a resource in your system that you want to map into Knock.
+ */
 export class Objects extends APIResource {
   bulk: BulkAPI.Bulk = new BulkAPI.Bulk(this._client);
 
@@ -423,6 +426,30 @@ export class Objects extends APIResource {
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
+
+  /**
+   * Unsets the preference set for the object, removing it entirely.
+   *
+   * @example
+   * ```ts
+   * await client.objects.unsetPreferences(
+   *   'collection',
+   *   'object_id',
+   *   'default',
+   * );
+   * ```
+   */
+  unsetPreferences(
+    collection: string,
+    objectID: string,
+    id: string,
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    return this._client.delete(path`/v1/objects/${collection}/${objectID}/preferences/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
 }
 
 export type ObjectsEntriesCursor = EntriesCursor<Object>;

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

@@ -6,6 +6,9 @@ import { MsTeamsPagination, type MsTeamsPaginationParams, PagePromise } from '..
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * A provider represents a third-party service that Knock integrates with and is configured via a channel.
+ */
 export class MsTeams extends APIResource {
   /**
    * Check if a connection to Microsoft Teams has been authorized for a given

package/src/resources/providers/slack.ts

@@ -6,6 +6,9 @@ import { PagePromise, SlackChannelsCursor, type SlackChannelsCursorParams } from
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * A provider represents a third-party service that Knock integrates with and is configured via a channel.
+ */
 export class Slack extends APIResource {
   /**
    * Check if a Slack channel is authenticated.

package/src/resources/schedules/bulk.ts

@@ -8,6 +8,9 @@ import * as TenantsAPI from '../tenants/tenants';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * A bulk operation is a set of changes applied across zero or more records triggered via a call to the Knock API and performed asynchronously.
+ */
 export class Bulk extends APIResource {
   /**
    * Bulk creates up to 1,000 schedules at a time. This endpoint also handles

package/src/resources/schedules/schedules.ts

@@ -9,6 +9,9 @@ import { APIPromise } from '../../core/api-promise';
 import { EntriesCursor, type EntriesCursorParams, PagePromise } from '../../core/pagination';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * A schedule is a per-recipient, timezone-aware configuration for when to invoke a workflow.
+ */
 export class Schedules extends APIResource {
   bulk: BulkAPI.Bulk = new BulkAPI.Bulk(this._client);
 

package/src/resources/shared.ts

@@ -33,6 +33,7 @@ export interface Condition {
     | 'is_timestamp_on_or_after_date'
     | 'is_timestamp_before_date'
     | 'is_timestamp_between'
+    | 'is_between'
     | 'is_audience_member'
     | 'is_not_audience_member';
 

package/src/resources/tenants/bulk.ts

@@ -6,6 +6,9 @@ import * as TenantsAPI from './tenants';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * A bulk operation is a set of changes applied across zero or more records triggered via a call to the Knock API and performed asynchronously.
+ */
 export class Bulk extends APIResource {
   /**
    * Delete up to 1,000 tenants at a time in a single operation. This operation

package/src/resources/tenants/tenants.ts

@@ -11,6 +11,9 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * A tenant represents a top-level entity from your system, like a company, organization, account, or workspace.
+ */
 export class Tenants extends APIResource {
   bulk: BulkAPI.Bulk = new BulkAPI.Bulk(this._client);
 

package/src/resources/users/bulk.ts

@@ -7,6 +7,9 @@ import * as UsersAPI from './users';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * A bulk operation is a set of changes applied across zero or more records triggered via a call to the Knock API and performed asynchronously.
+ */
 export class Bulk extends APIResource {
   /**
    * Permanently deletes up to 1,000 users at a time.

package/src/resources/users/feeds.ts

@@ -8,6 +8,9 @@ import { EntriesCursor, type EntriesCursorParams, PagePromise } from '../../core
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * A user is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.
+ */
 export class Feeds extends APIResource {
   /**
    * Returns the feed settings for a user.

package/src/resources/users/guides.ts

@@ -5,6 +5,9 @@ import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * A user is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.
+ */
 export class Guides extends APIResource {
   /**
    * Returns a list of eligible in-app guides for a specific user and channel.
@@ -193,6 +196,11 @@ export namespace GuideGetChannelResponse {
 
     channel_id?: string;
 
+    /**
+     * URL to this guide in the Knock dashboard
+     */
+    dashboard_url?: string;
+
     inserted_at?: string;
 
     /**

package/src/resources/users/users.ts

@@ -45,6 +45,9 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * A user is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.
+ */
 export class Users extends APIResource {
   feeds: FeedsAPI.Feeds = new FeedsAPI.Feeds(this._client);
   guides: GuidesAPI.Guides = new GuidesAPI.Guides(this._client);
@@ -364,6 +367,21 @@ export class Users extends APIResource {
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
+
+  /**
+   * Unsets the preference set for the user, removing it entirely.
+   *
+   * @example
+   * ```ts
+   * await client.users.unsetPreferences('user_id', 'default');
+   * ```
+   */
+  unsetPreferences(userID: string, id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/users/${userID}/preferences/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
 }
 
 export type UsersEntriesCursor = EntriesCursor<User>;

package/src/resources/workflow-recipient-runs.ts

@@ -0,0 +1,255 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as RecipientsAPI from './recipients/recipients';
+import { APIPromise } from '../core/api-promise';
+import { ItemsCursor, type ItemsCursorParams, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * A workflow run represents an individual execution of a workflow for a specific recipient.
+ */
+export class WorkflowRecipientRuns extends APIResource {
+  /**
+   * Returns a paginated list of workflow recipient runs for the current environment.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const workflowRecipientRun of client.workflowRecipientRuns.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: WorkflowRecipientRunListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<WorkflowRecipientRunsItemsCursor, WorkflowRecipientRun> {
+    return this._client.getAPIList('/v1/workflow_recipient_runs', ItemsCursor<WorkflowRecipientRun>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Returns a single workflow recipient run with its associated events.
+   *
+   * @example
+   * ```ts
+   * const workflowRecipientRunDetail =
+   *   await client.workflowRecipientRuns.get('id');
+   * ```
+   */
+  get(id: string, options?: RequestOptions): APIPromise<WorkflowRecipientRunDetail> {
+    return this._client.get(path`/v1/workflow_recipient_runs/${id}`, options);
+  }
+}
+
+export type WorkflowRecipientRunsItemsCursor = ItemsCursor<WorkflowRecipientRun>;
+
+/**
+ * A workflow recipient run represents an individual execution of a workflow for a
+ * specific recipient.
+ */
+export interface WorkflowRecipientRun {
+  /**
+   * The unique identifier for the workflow recipient run (per-recipient).
+   */
+  id: string;
+
+  /**
+   * The typename of the schema.
+   */
+  __typename: string;
+
+  /**
+   * Timestamp when the resource 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 current status of the workflow recipient run. One of `queued`, `processing`,
+   * `paused`, `completed`, or `cancelled`.
+   */
+  status: 'queued' | 'processing' | 'paused' | 'completed' | 'cancelled';
+
+  /**
+   * Describes how the workflow was triggered.
+   */
+  trigger_source: WorkflowRecipientRun.TriggerSource;
+
+  /**
+   * The timestamp when the resource was last updated.
+   */
+  updated_at: string;
+
+  /**
+   * The key of the workflow that was executed.
+   */
+  workflow: string;
+
+  /**
+   * The identifier for the top-level workflow run shared across all recipients in a
+   * single trigger.
+   */
+  workflow_run_id: string;
+
+  /**
+   * A recipient of a notification, which is either a user or an object.
+   */
+  actor?: RecipientsAPI.Recipient | null;
+
+  /**
+   * The number of errors encountered during the workflow recipient run.
+   */
+  error_count?: number;
+
+  /**
+   * The tenant associated with the workflow recipient run.
+   */
+  tenant?: string | null;
+}
+
+export namespace WorkflowRecipientRun {
+  /**
+   * Describes how the workflow was triggered.
+   */
+  export interface TriggerSource {
+    /**
+     * The type of trigger source. One of `api`, `audience`, `schedule`, `broadcast`,
+     * `workflow_step`, `integration`, or `rehearsal`.
+     */
+    type: 'api' | 'audience' | 'schedule' | 'broadcast' | 'workflow_step' | 'integration' | 'rehearsal';
+
+    /**
+     * The key of the audience that triggered the workflow.
+     */
+    audience_key?: string | null;
+
+    /**
+     * The cancellation key provided when the workflow was triggered via the API.
+     */
+    cancellation_key?: string | null;
+
+    /**
+     * The ID of the schedule that triggered the workflow.
+     */
+    schedule_id?: string | null;
+  }
+}
+
+/**
+ * A single workflow recipient run with its events.
+ */
+export interface WorkflowRecipientRunDetail extends WorkflowRecipientRun {
+  /**
+   * A list of events that occurred during the workflow recipient run.
+   */
+  events: Array<WorkflowRecipientRunEvent>;
+}
+
+/**
+ * An event that occurred during a workflow recipient run.
+ */
+export interface WorkflowRecipientRunEvent {
+  /**
+   * The unique identifier for the event.
+   */
+  id: string;
+
+  /**
+   * The typename of the schema.
+   */
+  __typename: string;
+
+  /**
+   * The type of event that occurred.
+   */
+  event: string;
+
+  /**
+   * Timestamp when the resource was created.
+   */
+  inserted_at: string;
+
+  /**
+   * Whether the event represents a successful or error state.
+   */
+  status: 'ok' | 'error';
+
+  /**
+   * The attempt number of the workflow recipient run event. Increments for each
+   * retry.
+   */
+  attempt?: number;
+
+  /**
+   * Event-specific data associated with the event.
+   */
+  data?: { [key: string]: unknown } | null;
+
+  /**
+   * The reference of the workflow step associated with this event.
+   */
+  step_ref?: string | null;
+
+  /**
+   * The type of workflow step associated with this event.
+   */
+  step_type?: string | null;
+}
+
+export interface WorkflowRecipientRunListParams extends ItemsCursorParams {
+  /**
+   * Limits the results to workflow recipient runs started before the given date.
+   */
+  ending_at?: string;
+
+  /**
+   * Limits the results to workflow recipient runs that have errors.
+   */
+  has_errors?: boolean;
+
+  /**
+   * Limits the results to workflow recipient runs for the given recipient. Accepts a
+   * user ID string or an object reference with `id` and `collection`.
+   */
+  recipient?: RecipientsAPI.RecipientReference;
+
+  /**
+   * Limits the results to workflow recipient runs started after the given date.
+   */
+  starting_at?: string;
+
+  /**
+   * Limits the results to workflow recipient runs with the given status.
+   */
+  status?: Array<'queued' | 'processing' | 'paused' | 'completed' | 'cancelled'>;
+
+  /**
+   * Limits the results to workflow recipient runs for the given tenant.
+   */
+  tenant?: string;
+
+  /**
+   * Limits the results to workflow recipient runs for the given workflow key.
+   */
+  workflow?: string;
+}
+
+export declare namespace WorkflowRecipientRuns {
+  export {
+    type WorkflowRecipientRun as WorkflowRecipientRun,
+    type WorkflowRecipientRunDetail as WorkflowRecipientRunDetail,
+    type WorkflowRecipientRunEvent as WorkflowRecipientRunEvent,
+    type WorkflowRecipientRunsItemsCursor as WorkflowRecipientRunsItemsCursor,
+    type WorkflowRecipientRunListParams as WorkflowRecipientRunListParams,
+  };
+}

package/src/resources/workflows.ts

@@ -8,6 +8,9 @@ import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * A workflow is a structured set of steps that is triggered to produce notifications sent over channels.
+ */
 export class Workflows extends APIResource {
   /**
    * When invoked for a workflow using a specific workflow key and cancellation key,

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '1.29.1'; // x-release-please-version
+export const VERSION = '1.31.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.29.1";
+export declare const VERSION = "1.31.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.29.1";
+export declare const VERSION = "1.31.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '1.29.1'; // x-release-please-version
+exports.VERSION = '1.31.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '1.29.1'; // x-release-please-version
+export const VERSION = '1.31.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map