@knocklabs/node 0.6.19 → 1.1.0

package/src/resources/users/feeds.ts

@@ -0,0 +1,315 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as MessagesAPI from '../messages/messages';
+import * as RecipientsAPI from '../recipients/recipients';
+import { APIPromise } from '../../core/api-promise';
+import { EntriesCursor, type EntriesCursorParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+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);
+  }
+
+  /**
+   * 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,
+    id: string,
+    query: FeedListItemsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<FeedListItemsResponsesEntriesCursor, FeedListItemsResponse> {
+    return this._client.getAPIList(
+      path`/v1/users/${userID}/feeds/${id}`,
+      EntriesCursor<FeedListItemsResponse>,
+      { query, ...options },
+    );
+  }
+}
+
+export type FeedListItemsResponsesEntriesCursor = EntriesCursor<FeedListItemsResponse>;
+
+/**
+ * The response for the user's feed settings.
+ */
+export interface FeedGetSettingsResponse {
+  /**
+   * Features configuration for the user's feed.
+   */
+  features: FeedGetSettingsResponse.Features;
+}
+
+export namespace FeedGetSettingsResponse {
+  /**
+   * Features configuration for the user's feed.
+   */
+  export interface Features {
+    /**
+     * Whether branding is required for the user's feed.
+     */
+    branding_required: boolean;
+  }
+}
+
+/**
+ * An in-app feed message in a user's feed.
+ */
+export interface FeedListItemsResponse {
+  /**
+   * Unique identifier for the feed.
+   */
+  id: string;
+
+  /**
+   * The typename of the schema.
+   */
+  __typename: string;
+
+  /**
+   * List of activities associated with this feed item.
+   */
+  activities: Array<MessagesAPI.Activity>;
+
+  /**
+   * List of actors associated with this feed item.
+   */
+  actors: Array<RecipientsAPI.Recipient>;
+
+  /**
+   * Content blocks that make up the feed item.
+   */
+  blocks: Array<
+    FeedListItemsResponse.MessageInAppFeedContentBlock | FeedListItemsResponse.MessageInAppFeedButtonSetBlock
+  >;
+
+  /**
+   * Additional data associated with the feed item.
+   */
+  data: Record<string, unknown> | null;
+
+  /**
+   * Timestamp when the resource was created.
+   */
+  inserted_at: string;
+
+  /**
+   * Source information for the feed item.
+   */
+  source: FeedListItemsResponse.Source;
+
+  /**
+   * Tenant ID that the feed item belongs to.
+   */
+  tenant: string | null;
+
+  /**
+   * Total number of activities related to this feed item.
+   */
+  total_activities: number;
+
+  /**
+   * Total number of actors related to this feed item.
+   */
+  total_actors: number;
+
+  /**
+   * The timestamp when the resource was last updated.
+   */
+  updated_at: string;
+
+  /**
+   * Timestamp when the feed item was archived.
+   */
+  archived_at?: string | null;
+
+  /**
+   * Timestamp when the feed item was clicked.
+   */
+  clicked_at?: string | null;
+
+  /**
+   * Timestamp when the feed item was interacted with.
+   */
+  interacted_at?: string | null;
+
+  /**
+   * Timestamp when a link within the feed item was clicked.
+   */
+  link_clicked_at?: string | null;
+
+  /**
+   * Timestamp when the feed item was marked as read.
+   */
+  read_at?: string | null;
+
+  /**
+   * Timestamp when the feed item was marked as seen.
+   */
+  seen_at?: string | null;
+}
+
+export namespace FeedListItemsResponse {
+  /**
+   * A block in a message in an app feed.
+   */
+  export interface MessageInAppFeedContentBlock {
+    /**
+     * The content of the block in a message in an app feed.
+     */
+    content: string;
+
+    /**
+     * The name of the block in a message in an app feed.
+     */
+    name: string;
+
+    /**
+     * The rendered HTML version of the content.
+     */
+    rendered: string;
+
+    /**
+     * The type of block in a message in an app feed.
+     */
+    type: 'markdown' | 'text';
+  }
+
+  /**
+   * A button set block in a message in an app feed.
+   */
+  export interface MessageInAppFeedButtonSetBlock {
+    /**
+     * A list of buttons in an in app feed message.
+     */
+    buttons: Array<MessageInAppFeedButtonSetBlock.Button>;
+
+    /**
+     * The name of the button set in a message in an app feed.
+     */
+    name: string;
+
+    /**
+     * The type of block in a message in an app feed.
+     */
+    type: 'button_set';
+  }
+
+  export namespace MessageInAppFeedButtonSetBlock {
+    /**
+     * A button in an in app feed message.
+     */
+    export interface Button {
+      /**
+       * The action to take when the button is clicked.
+       */
+      action: string;
+
+      /**
+       * The label of the button.
+       */
+      label: string;
+
+      /**
+       * The name of the button.
+       */
+      name: string;
+    }
+  }
+
+  /**
+   * Source information for the feed item.
+   */
+  export interface Source {
+    /**
+     * The typename of the schema.
+     */
+    __typename: string;
+
+    /**
+     * Categories this workflow belongs to.
+     */
+    categories: Array<string>;
+
+    /**
+     * The key of the workflow.
+     */
+    key: string;
+
+    /**
+     * The workflow version ID.
+     */
+    version_id: string;
+  }
+}
+
+export interface FeedListItemsParams extends EntriesCursorParams {
+  /**
+   * The archived status of the feed items.
+   */
+  archived?: 'exclude' | 'include' | 'only';
+
+  /**
+   * Whether the feed items have a tenant.
+   */
+  has_tenant?: boolean;
+
+  /**
+   * The source of the feed items.
+   */
+  source?: string;
+
+  /**
+   * The status of the feed items.
+   */
+  status?: 'unread' | 'read' | 'unseen' | 'seen' | 'all';
+
+  /**
+   * The tenant associated with the feed items.
+   */
+  tenant?: string;
+
+  /**
+   * The trigger data of the feed items (as a JSON string).
+   */
+  trigger_data?: string;
+
+  /**
+   * The workflow categories of the feed items.
+   */
+  workflow_categories?: Array<string>;
+}
+
+export declare namespace Feeds {
+  export {
+    type FeedGetSettingsResponse as FeedGetSettingsResponse,
+    type FeedListItemsResponse as FeedListItemsResponse,
+    type FeedListItemsResponsesEntriesCursor as FeedListItemsResponsesEntriesCursor,
+    type FeedListItemsParams as FeedListItemsParams,
+  };
+}

package/src/resources/users/guides.ts

@@ -0,0 +1,386 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+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,
+    channelID: string,
+    query: GuideGetChannelParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<GuideGetChannelResponse> {
+    return this._client.get(path`/v1/users/${userID}/guides/${channelID}`, { query, ...options });
+  }
+
+  /**
+   * 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,
+    messageID: string,
+    body: GuideMarkMessageAsArchivedParams,
+    options?: RequestOptions,
+  ): APIPromise<GuideMarkMessageAsArchivedResponse> {
+    return this._client.put(path`/v1/users/${userID}/guides/messages/${messageID}/archived`, {
+      body,
+      ...options,
+    });
+  }
+
+  /**
+   * 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,
+    messageID: string,
+    body: GuideMarkMessageAsInteractedParams,
+    options?: RequestOptions,
+  ): APIPromise<GuideMarkMessageAsInteractedResponse> {
+    return this._client.put(path`/v1/users/${userID}/guides/messages/${messageID}/interacted`, {
+      body,
+      ...options,
+    });
+  }
+
+  /**
+   * 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,
+    messageID: string,
+    body: GuideMarkMessageAsSeenParams,
+    options?: RequestOptions,
+  ): APIPromise<GuideMarkMessageAsSeenResponse> {
+    return this._client.put(path`/v1/users/${userID}/guides/messages/${messageID}/seen`, {
+      body,
+      ...options,
+    });
+  }
+}
+
+/**
+ * A response for a list of guides.
+ */
+export interface GuideGetChannelResponse {
+  /**
+   * A list of guides.
+   */
+  guides: Array<GuideGetChannelResponse.Guide>;
+
+  /**
+   * The recipient of the guide.
+   */
+  recipient?: GuideGetChannelResponse.Recipient | null;
+}
+
+export namespace GuideGetChannelResponse {
+  export interface Guide {
+    /**
+     * The unique identifier for the guide.
+     */
+    id?: string;
+
+    /**
+     * The content of the guide.
+     */
+    content?: string;
+
+    /**
+     * The metadata of the guide.
+     */
+    metadata?: Record<string, unknown>;
+
+    /**
+     * The title of the guide.
+     */
+    title?: string;
+  }
+
+  /**
+   * The recipient of the guide.
+   */
+  export interface Recipient {
+    /**
+     * Unique identifier for the recipient.
+     */
+    id?: string;
+  }
+}
+
+/**
+ * A response for a guide action.
+ */
+export interface GuideMarkMessageAsArchivedResponse {
+  /**
+   * The status of a guide's action.
+   */
+  status: string;
+}
+
+/**
+ * A response for a guide action.
+ */
+export interface GuideMarkMessageAsInteractedResponse {
+  /**
+   * The status of a guide's action.
+   */
+  status: string;
+}
+
+/**
+ * A response for a guide action.
+ */
+export interface GuideMarkMessageAsSeenResponse {
+  /**
+   * The status of a guide's action.
+   */
+  status: string;
+}
+
+export interface GuideGetChannelParams {
+  /**
+   * The data (JSON encoded object) to use for targeting and rendering guides.
+   */
+  data?: string;
+
+  /**
+   * The tenant ID to use for targeting and rendering guides.
+   */
+  tenant?: string;
+
+  /**
+   * The type of guides to filter by.
+   */
+  type?: string;
+}
+
+export interface GuideMarkMessageAsArchivedParams {
+  /**
+   * The unique identifier for the channel.
+   */
+  channel_id: string;
+
+  /**
+   * The unique identifier for the guide.
+   */
+  guide_id: string;
+
+  /**
+   * The key of the guide.
+   */
+  guide_key: string;
+
+  /**
+   * The step reference of the guide.
+   */
+  guide_step_ref: string;
+
+  /**
+   * The content of the guide.
+   */
+  content?: Record<string, unknown>;
+
+  /**
+   * The data of the guide.
+   */
+  data?: Record<string, unknown>;
+
+  /**
+   * Whether the guide is final.
+   */
+  is_final?: boolean;
+
+  /**
+   * The metadata of the guide.
+   */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * The tenant ID of the guide.
+   */
+  tenant?: string | null;
+}
+
+export interface GuideMarkMessageAsInteractedParams {
+  /**
+   * The unique identifier for the channel.
+   */
+  channel_id: string;
+
+  /**
+   * The unique identifier for the guide.
+   */
+  guide_id: string;
+
+  /**
+   * The key of the guide.
+   */
+  guide_key: string;
+
+  /**
+   * The step reference of the guide.
+   */
+  guide_step_ref: string;
+
+  /**
+   * The content of the guide.
+   */
+  content?: Record<string, unknown>;
+
+  /**
+   * The data of the guide.
+   */
+  data?: Record<string, unknown>;
+
+  /**
+   * Whether the guide is final.
+   */
+  is_final?: boolean;
+
+  /**
+   * The metadata of the guide.
+   */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * The tenant ID of the guide.
+   */
+  tenant?: string | null;
+}
+
+export interface GuideMarkMessageAsSeenParams {
+  /**
+   * The unique identifier for the channel.
+   */
+  channel_id: string;
+
+  /**
+   * The unique identifier for the guide.
+   */
+  guide_id: string;
+
+  /**
+   * The key of the guide.
+   */
+  guide_key: string;
+
+  /**
+   * The step reference of the guide.
+   */
+  guide_step_ref: string;
+
+  /**
+   * The content of the guide.
+   */
+  content?: Record<string, unknown>;
+
+  /**
+   * The data of the guide.
+   */
+  data?: Record<string, unknown>;
+
+  /**
+   * Whether the guide is final.
+   */
+  is_final?: boolean;
+
+  /**
+   * The metadata of the guide.
+   */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * The tenant ID of the guide.
+   */
+  tenant?: string | null;
+}
+
+export declare namespace Guides {
+  export {
+    type GuideGetChannelResponse as GuideGetChannelResponse,
+    type GuideMarkMessageAsArchivedResponse as GuideMarkMessageAsArchivedResponse,
+    type GuideMarkMessageAsInteractedResponse as GuideMarkMessageAsInteractedResponse,
+    type GuideMarkMessageAsSeenResponse as GuideMarkMessageAsSeenResponse,
+    type GuideGetChannelParams as GuideGetChannelParams,
+    type GuideMarkMessageAsArchivedParams as GuideMarkMessageAsArchivedParams,
+    type GuideMarkMessageAsInteractedParams as GuideMarkMessageAsInteractedParams,
+    type GuideMarkMessageAsSeenParams as GuideMarkMessageAsSeenParams,
+  };
+}