@knocklabs/client 0.20.4 → 0.21.1

package/src/clients/feed/interfaces.ts

@@ -48,6 +48,16 @@ export interface FeedClientOptions {
     // Optionally set whether to be inclusive of the start and end dates
     inclusive?: boolean;
   };
+  /**
+   * The mode to render the feed items in. When `mode` is `compact`:
+   *
+   * - The `activities` and `total_activities` fields will _not_ be present on feed items
+   * - The `data` field will _not_ include nested arrays and objects
+   * - The `actors` field will only have up to one actor
+   *
+   * @default "compact"
+   */
+  mode?: "rich" | "compact";
 }
 
 export type FetchFeedOptions = {
@@ -55,14 +65,25 @@ export type FetchFeedOptions = {
   __fetchSource?: "socket" | "http";
 } & Omit<FeedClientOptions, "__experimentalCrossBrowserUpdates">;
 
-// The final data shape that is sent to the API
-// Should match types here: https://docs.knock.app/reference#get-feed
+/**
+ * The final data shape that is sent to the the list feed items endpoint of the Knock API.
+ *
+ * @see https://docs.knock.app/api-reference/users/feeds/list_items
+ */
 export type FetchFeedOptionsForRequest = Omit<
   FeedClientOptions,
-  "trigger_data"
+  "trigger_data" | "inserted_at_date_range"
 > & {
-  // Formatted trigger data into a string
+  /** The trigger data of the feed items (as a JSON string). */
   trigger_data?: string;
+  /** Limits the results to items inserted after or on the given date. */
+  "inserted_at.gte"?: string;
+  /** Limits the results to items inserted before or on the given date. */
+  "inserted_at.lte"?: string;
+  /** Limits the results to items inserted after the given date. */
+  "inserted_at.gt"?: string;
+  /** Limits the results to items inserted before the given date. */
+  "inserted_at.lt"?: string;
   // Unset options that should not be sent to the API
   __loadingType: undefined;
   __fetchSource: undefined;
@@ -107,7 +128,11 @@ export type ContentBlock =
 export interface FeedItem<T = GenericData> {
   __cursor: string;
   id: string;
-  activities: Activity<T>[];
+  /**
+   * List of activities associated with this feed item.
+   * Only present in "rich" mode.
+   */
+  activities?: Activity<T>[];
   actors: Recipient[];
   blocks: ContentBlock[];
   inserted_at: string;
@@ -118,7 +143,11 @@ export interface FeedItem<T = GenericData> {
   interacted_at: string | null;
   link_clicked_at: string | null;
   archived_at: string | null;
-  total_activities: number;
+  /**
+   * Total number of activities related to this feed item.
+   * Only present in "rich" mode.
+   */
+  total_activities?: number;
   total_actors: number;
   data: T | null;
   source: NotificationSource;

package/src/clients/feed/utils.ts

@@ -1,4 +1,8 @@
-import type { FeedClientOptions, FeedItem } from "./interfaces";
+import type {
+  FeedClientOptions,
+  FeedItem,
+  FetchFeedOptionsForRequest,
+} from "./interfaces";
 
 export function deduplicateItems(items: FeedItem[]): FeedItem[] {
   const seen: Record<string, boolean> = {};
@@ -22,6 +26,11 @@ export function sortItems(items: FeedItem[]) {
   });
 }
 
+type DateRangeParams = Pick<
+  FetchFeedOptionsForRequest,
+  "inserted_at.gte" | "inserted_at.lte" | "inserted_at.gt" | "inserted_at.lt"
+>;
+
 export function mergeDateRangeParams(options: FeedClientOptions) {
   const { inserted_at_date_range, ...rest } = options;
 
@@ -29,7 +38,7 @@ export function mergeDateRangeParams(options: FeedClientOptions) {
     return rest;
   }
 
-  const dateRangeParams: Record<string, string> = {};
+  const dateRangeParams: DateRangeParams = {};
 
   // Determine which operators to use based on the inclusive flag
   const isInclusive = inserted_at_date_range.inclusive ?? false;

package/src/clients/guide/client.ts

@@ -157,34 +157,16 @@ const select = (state: StoreState, filters: SelectFilterParams = {}) => {
   const defaultGroup = findDefaultGroup(state.guideGroups);
   if (!defaultGroup) return result;
 
-  const displaySequence = [...defaultGroup.display_sequence];
+  const displaySequence = defaultGroup.display_sequence;
   const location = state.location;
 
-  // If in debug mode, put the forced guide at the beginning of the display sequence.
-  if (state.debug.forcedGuideKey) {
-    const forcedKeyIndex = displaySequence.indexOf(state.debug.forcedGuideKey);
-    if (forcedKeyIndex > -1) {
-      displaySequence.splice(forcedKeyIndex, 1);
-    }
-    displaySequence.unshift(state.debug.forcedGuideKey);
-  }
-
   for (const [index, guideKey] of displaySequence.entries()) {
-    let guide = state.guides[guideKey];
-
-    // Use preview guide if it exists and matches the forced guide key
-    if (
-      state.debug.forcedGuideKey === guideKey &&
-      state.previewGuides[guideKey]
-    ) {
-      guide = state.previewGuides[guideKey];
-    }
-
+    const guide = state.previewGuides[guideKey] || state.guides[guideKey];
     if (!guide) continue;
 
-    const affirmed = predicate(guide, {
+    const affirmed = predicate(guide, filters, {
       location,
-      filters,
+      ineligibleGuides: state.ineligibleGuides,
       debug: state.debug,
     });
 
@@ -197,15 +179,15 @@ const select = (state: StoreState, filters: SelectFilterParams = {}) => {
   return result;
 };
 
-type PredicateOpts = {
-  location?: string | undefined;
-  filters?: SelectFilterParams | undefined;
-  debug: DebugState;
-};
+type PredicateOpts = Pick<
+  StoreState,
+  "location" | "ineligibleGuides" | "debug"
+>;
 
 const predicate = (
   guide: KnockGuide,
-  { location, filters = {}, debug = {} }: PredicateOpts,
+  filters: SelectFilterParams,
+  { location, ineligibleGuides = {}, debug = {} }: PredicateOpts,
 ) => {
   if (filters.type && filters.type !== guide.type) {
     return false;
@@ -215,11 +197,16 @@ const predicate = (
     return false;
   }
 
-  // Bypass filtering if the debugged guide matches the given filters.
-  // This should always run AFTER checking the filters but BEFORE
-  // checking archived status and location rules.
-  if (debug.forcedGuideKey === guide.key) {
-    return true;
+  // If in debug mode with a forced guide key, bypass other filtering and always
+  // return true for that guide only. This should always run AFTER checking the
+  // filters but BEFORE checking archived status and location rules.
+  if (debug.forcedGuideKey) {
+    return debug.forcedGuideKey === guide.key;
+  }
+
+  const ineligible = ineligibleGuides[guide.key];
+  if (ineligible) {
+    return false;
   }
 
   if (!guide.active) {
@@ -230,6 +217,13 @@ const predicate = (
     return false;
   }
 
+  return checkActivatable(guide, location);
+};
+
+export const checkActivatable = (
+  guide: KnockGuide,
+  location: string | undefined,
+) => {
   const url = location ? newUrl(location) : undefined;
 
   const urlRules = guide.activation_url_rules || [];
@@ -283,18 +277,21 @@ export class KnockGuideClient {
   ) {
     const {
       trackLocationFromWindow = true,
+      // TODO(KNO-11523): Remove once we ship guide toolbar v2, and offload as
+      // much debugging specific logic and responsibilities to toolbar.
+      trackDebugParams = false,
       throttleCheckInterval = DEFAULT_COUNTER_INCREMENT_INTERVAL,
     } = options;
     const win = checkForWindow();
 
     const location = trackLocationFromWindow ? win?.location?.href : undefined;
-
-    const debug = detectDebugParams();
+    const debug = trackDebugParams ? detectDebugParams() : undefined;
 
     this.store = new Store<StoreState>({
       guideGroups: [],
       guideGroupDisplayLogs: {},
       guides: {},
+      ineligibleGuides: {},
       previewGuides: {},
       queries: {},
       location,
@@ -376,7 +373,12 @@ export class KnockGuideClient {
       >(this.channelId, queryParams);
       queryStatus = { status: "ok" };
 
-      const { entries, guide_groups: groups, guide_group_display_logs } = data;
+      const {
+        entries,
+        guide_groups: groups,
+        guide_group_display_logs,
+        ineligible_guides,
+      } = data;
 
       this.knock.log("[Guide] Loading fetched guides");
       this.store.setState((state) => ({
@@ -384,6 +386,7 @@ export class KnockGuideClient {
         guideGroups: groups?.length > 0 ? groups : [mockDefaultGroup(entries)],
         guideGroupDisplayLogs: guide_group_display_logs || {},
         guides: byKey(entries.map((g) => this.localCopy(g))),
+        ineligibleGuides: byKey(ineligible_guides || []),
         queries: { ...state.queries, [queryKey]: queryStatus },
       }));
     } catch (e) {
@@ -418,8 +421,9 @@ export class KnockGuideClient {
     const params = {
       ...this.targetParams,
       user_id: this.knock.userId,
-      force_all_guides: debugState.forcedGuideKey ? true : undefined,
-      preview_session_id: debugState.previewSessionId || undefined,
+      force_all_guides:
+        debugState?.forcedGuideKey || debugState?.debugging ? true : undefined,
+      preview_session_id: debugState?.previewSessionId || undefined,
     };
 
     const newChannel = this.socket.channel(this.socketChannelTopic, params);
@@ -484,6 +488,8 @@ export class KnockGuideClient {
   private handleSocketEvent(payload: GuideSocketEvent) {
     const { event, data } = payload;
 
+    // TODO(KNO-11489): Include an ineligible guide in the socket payload too
+    // and process it when handling socket events in real time.
     switch (event) {
       case "guide.added":
         return this.addOrReplaceGuide(payload);
@@ -565,6 +571,39 @@ export class KnockGuideClient {
     }
   }
 
+  setDebug(debugOpts?: Omit<DebugState, "debugging">) {
+    this.knock.log("[Guide] .setDebug()");
+    const shouldRefetch = !this.store.state.debug?.debugging;
+
+    this.store.setState((state) => ({
+      ...state,
+      debug: { ...debugOpts, debugging: true },
+    }));
+
+    if (shouldRefetch) {
+      this.knock.log(
+        `[Guide] Start debugging, refetching guides and resubscribing to the websocket channel`,
+      );
+      this.fetch();
+      this.subscribe();
+    }
+  }
+
+  unsetDebug() {
+    this.knock.log("[Guide] .unsetDebug()");
+    const shouldRefetch = this.store.state.debug?.debugging;
+
+    this.store.setState((state) => ({ ...state, debug: undefined }));
+
+    if (shouldRefetch) {
+      this.knock.log(
+        `[Guide] Stop debugging, refetching guides and resubscribing to the websocket channel`,
+      );
+      this.fetch();
+      this.subscribe();
+    }
+  }
+
   //
   // Store selector
   //
@@ -736,17 +775,8 @@ export class KnockGuideClient {
     // callback to a setTimeout, but just to be safe.
     this.ensureClearTimeout();
 
-    // If in debug mode, try to resolve the forced guide, otherwise return the first non-undefined guide.
-    let resolved = undefined;
-    if (this.store.state.debug.forcedGuideKey) {
-      resolved = this.stage.ordered.find(
-        (x) => x === this.store.state.debug.forcedGuideKey,
-      );
-    }
-
-    if (!resolved) {
-      resolved = this.stage.ordered.find((x) => x !== undefined);
-    }
+    // Resolve to the first non-undefined guide in the stage.
+    const resolved = this.stage.ordered.find((x) => x !== undefined);
 
     this.knock.log(
       `[Guide] Closing the current group stage: resolved=${resolved}`,
@@ -937,7 +967,7 @@ export class KnockGuideClient {
       // Get the next unarchived step.
       getStep() {
         // If debugging this guide, return the first step regardless of archive status
-        if (self.store.state.debug.forcedGuideKey === this.key) {
+        if (self.store.state.debug?.forcedGuideKey === this.key) {
           return this.steps[0];
         }
 
@@ -994,7 +1024,7 @@ export class KnockGuideClient {
 
     // Append debug params
     const debugState = this.store.state.debug;
-    if (debugState.forcedGuideKey) {
+    if (debugState?.forcedGuideKey || debugState?.debugging) {
       combinedParams.force_all_guides = true;
     }
 
@@ -1163,8 +1193,15 @@ export class KnockGuideClient {
 
     this.knock.log(`[Guide] Detected a location change: ${href}`);
 
+    if (!this.options.trackDebugParams) {
+      this.setLocation(href);
+      return;
+    }
+
+    // TODO(KNO-11523): Remove below once we ship toolbar v2.
+
     // If entering debug mode, fetch all guides.
-    const currentDebugParams = this.store.state.debug;
+    const currentDebugParams = this.store.state.debug || {};
     const newDebugParams = detectDebugParams();
 
     this.setLocation(href, { debug: newDebugParams });

package/src/clients/guide/index.ts

@@ -1,9 +1,15 @@
-export { KnockGuideClient, DEBUG_QUERY_PARAMS } from "./client";
+export {
+  KnockGuideClient,
+  DEBUG_QUERY_PARAMS,
+  checkActivatable,
+} from "./client";
 export type {
   KnockGuide,
   KnockGuideStep,
+  GuideIneligibilityMarker as KnockGuideIneligibilityMarker,
   TargetParams as KnockGuideTargetParams,
   SelectFilterParams as KnockGuideFilterParams,
   SelectGuideOpts as KnockSelectGuideOpts,
   SelectGuidesOpts as KnockSelectGuidesOpts,
+  StoreState as KnockGuideClientStoreState,
 } from "./types";

package/src/clients/guide/types.ts

@@ -65,6 +65,19 @@ export interface GuideGroupData {
   updated_at: string;
 }
 
+type GuideIneligibilityReason =
+  | "guide_not_active"
+  | "marked_as_archived"
+  | "target_conditions_not_met"
+  | "not_in_target_audience";
+
+export type GuideIneligibilityMarker = {
+  __typename: "GuideIneligibilityMarker";
+  key: KnockGuide["key"];
+  reason: GuideIneligibilityReason;
+  message: string;
+};
+
 export type GetGuidesQueryParams = {
   data?: string;
   tenant?: string;
@@ -76,6 +89,7 @@ export type GetGuidesResponse = {
   entries: GuideData[];
   guide_groups: GuideGroupData[];
   guide_group_display_logs: Record<GuideGroupData["key"], string>;
+  ineligible_guides: GuideIneligibilityMarker[];
 };
 
 //
@@ -194,6 +208,7 @@ export type QueryStatus = {
 };
 
 export type DebugState = {
+  debugging?: boolean;
   forcedGuideKey?: string | null;
   previewSessionId?: string | null;
 };
@@ -202,11 +217,15 @@ export type StoreState = {
   guideGroups: GuideGroupData[];
   guideGroupDisplayLogs: Record<GuideGroupData["key"], string>;
   guides: Record<KnockGuide["key"], KnockGuide>;
+  ineligibleGuides: Record<
+    GuideIneligibilityMarker["key"],
+    GuideIneligibilityMarker
+  >;
   previewGuides: Record<KnockGuide["key"], KnockGuide>;
   queries: Record<QueryKey, QueryStatus>;
   location: string | undefined;
   counter: number;
-  debug: DebugState;
+  debug?: DebugState;
 };
 
 export type QueryFilterParams = Pick<GetGuidesQueryParams, "type">;
@@ -229,6 +248,7 @@ export type TargetParams = {
 
 export type ConstructorOpts = {
   trackLocationFromWindow?: boolean;
+  trackDebugParams?: boolean;
   orderResolutionDuration?: number;
   throttleCheckInterval?: number;
 };