@knocklabs/client 0.14.4 → 0.14.6

package/src/clients/feed/socket-manager.ts

@@ -0,0 +1,185 @@
+import { Store } from "@tanstack/store";
+import { Channel, Socket } from "phoenix";
+
+import Feed from "./feed";
+import type { FeedClientOptions, FeedMetadata } from "./interfaces";
+
+export const SocketEventType = {
+  NewMessage: "new-message",
+} as const;
+
+const SOCKET_EVENT_TYPES = [SocketEventType.NewMessage];
+
+type ClientQueryParams = FeedClientOptions;
+
+// e.g. feeds:<channel_id>:<user_id>
+type ChannelTopic = string;
+
+// Unique reference id of a feed client
+type ClientReferenceId = string;
+
+type NewMessageEventPayload = {
+  event: typeof SocketEventType.NewMessage;
+  /**
+   * @deprecated Top-level feed metadata. Exists for legacy reasons.
+   */
+  metadata: FeedMetadata;
+  /** Feed metadata, keyed by client reference id. */
+  data: Record<ClientReferenceId, { metadata: FeedMetadata }>;
+};
+
+export type SocketEventPayload = NewMessageEventPayload;
+
+// "attn" field contains a list of client reference ids that should be notified
+// of a socket event.
+type WithAttn<P> = P & { attn: ClientReferenceId[] };
+
+type FeedSocketInbox = Record<ClientReferenceId, SocketEventPayload>;
+
+/*
+ * Manages socket subscriptions for feeds, allowing multiple feed clients
+ * to listen for real time updates from the socket API via a single socket
+ * connection.
+ */
+export class FeedSocketManager {
+  // Mapping of live channels by topic. Note, there can be one or more feed
+  // client(s) that can subscribe.
+  private channels: Record<ChannelTopic, Channel>;
+
+  // Mapping of query params for each feeds client, partitioned by reference id,
+  // and grouped by channel topic. It's a double nested object that looks like:
+  //  {
+  //    "feeds:<channel_1>:<user_1>": {
+  //      "ref-1": {
+  //        "tenant": "foo",
+  //      },
+  //      "ref-2": {
+  //        "tenant": "bar",
+  //      },
+  //    },
+  //    "feeds:<channel_2>:<user_1>": {
+  //      "ref-3": {
+  //        "tenant": "baz",
+  //      },
+  //    }
+  //  }
+  //
+  // Each time a new feed client joins a channel, we send all cumulated
+  // params such that the socket API can apply filtering rules and figure out
+  // which feed clients should be notified based on reference ids in
+  // "attn" field of the event payload when sending out an event.
+  private params: Record<
+    ChannelTopic,
+    Record<ClientReferenceId, ClientQueryParams>
+  >;
+
+  // A reactive store that captures a new socket event, that notifies any feed
+  // clients that have subscribed.
+  private inbox: Store<
+    FeedSocketInbox,
+    (cb: FeedSocketInbox) => FeedSocketInbox
+  >;
+
+  constructor(readonly socket: Socket) {
+    this.channels = {};
+    this.params = {};
+    this.inbox = new Store<FeedSocketInbox>({});
+  }
+
+  join(feed: Feed) {
+    const topic = feed.socketChannelTopic;
+    const referenceId = feed.referenceId;
+    const params = feed.defaultOptions;
+
+    // Ensure a live socket connection if not yet connected.
+    if (!this.socket.isConnected()) {
+      this.socket.connect();
+    }
+
+    // If a new feed client joins, or has updated query params, then
+    // track the updated params and (re)join with the latest query params.
+    // Note, each time we send combined params of all feed clients that
+    // have subscribed for a given feed channel and user, grouped by
+    // client's reference id.
+    if (!this.params[topic]) {
+      this.params[topic] = {};
+    }
+
+    const maybeParams = this.params[topic][referenceId];
+    const hasNewOrUpdatedParams =
+      !maybeParams || JSON.stringify(maybeParams) !== JSON.stringify(params);
+
+    if (hasNewOrUpdatedParams) {
+      // Tracks all subscribed clients' params by reference id and by topic.
+      this.params[topic] = { ...this.params[topic], [referenceId]: params };
+    }
+
+    if (!this.channels[topic] || hasNewOrUpdatedParams) {
+      const newChannel = this.socket.channel(topic, this.params[topic]);
+      for (const eventType of SOCKET_EVENT_TYPES) {
+        newChannel.on(eventType, (payload) => this.setInbox(payload));
+      }
+      // Tracks live channels by channel topic.
+      this.channels[topic] = newChannel;
+    }
+
+    const channel = this.channels[topic];
+
+    // Join the channel if not already joined or joining or leaving.
+    if (["closed", "errored"].includes(channel.state)) {
+      channel.join();
+    }
+
+    // Let the feed client subscribe to the "inbox", so it can be notified
+    // when there's a new socket event that is relevant to it
+    const unsub = this.inbox.subscribe(() => {
+      const payload = this.inbox.state[referenceId];
+      if (!payload) return;
+
+      feed.handleSocketEvent(payload);
+    });
+
+    return unsub;
+  }
+
+  leave(feed: Feed) {
+    feed.unsubscribeFromSocketEvents?.();
+
+    const topic = feed.socketChannelTopic;
+    const referenceId = feed.referenceId;
+
+    const partitionedParams = { ...this.params };
+    const paramsForTopic = partitionedParams[topic] || {};
+    const paramsForReferenceClient = paramsForTopic[referenceId];
+
+    if (paramsForReferenceClient) {
+      delete paramsForTopic[referenceId];
+    }
+
+    const channels = { ...this.channels };
+    const channelForTopic = channels[topic];
+    if (channelForTopic && Object.keys(paramsForTopic).length === 0) {
+      for (const eventType of SOCKET_EVENT_TYPES) {
+        channelForTopic.off(eventType);
+      }
+      channelForTopic.leave();
+      delete channels[topic];
+    }
+
+    this.params = partitionedParams;
+    this.channels = channels;
+  }
+
+  private setInbox(payload: WithAttn<SocketEventPayload>) {
+    const { attn, ...rest } = payload;
+
+    // Set the incoming socket event into the inbox, keyed by relevant client
+    // reference ids provided by the server (via attn field), so we can notify
+    // only the clients that need to be notified.
+    this.inbox.setState(() =>
+      attn.reduce((acc, referenceId) => {
+        return { ...acc, [referenceId]: rest };
+      }, {}),
+    );
+  }
+}

package/src/clients/feed/types.ts

@@ -3,6 +3,7 @@ import { GenericData, PageInfo } from "@knocklabs/types";
 import { NetworkStatus } from "../../networkStatus";
 
 import { FeedItem, FeedMetadata, FeedResponse } from "./interfaces";
+import { SocketEventPayload, SocketEventType } from "./socket-manager";
 
 export type StoreFeedResultOptions = {
   shouldSetPage?: boolean;
@@ -22,9 +23,10 @@ export interface FeedStoreState {
   resetStore: (metadata?: FeedMetadata) => void;
 }
 
-export interface FeedMessagesReceivedPayload {
-  metadata: FeedMetadata;
-}
+export type FeedMessagesReceivedPayload = Extract<
+  SocketEventPayload,
+  { event: typeof SocketEventType.NewMessage }
+>;
 
 /*
 Event types:

package/src/clients/guide/client.ts

@@ -1,6 +1,7 @@
 import { GenericData } from "@knocklabs/types";
 import { Store } from "@tanstack/store";
 import { Channel, Socket } from "phoenix";
+import { URLPattern } from "urlpattern-polyfill";
 
 import Knock from "../../knock";
 
@@ -38,6 +39,11 @@ interface GuideStepData {
   content: any;
 }
 
+interface GuideActivationLocationRuleData {
+  directive: "allow" | "block";
+  pathname: string;
+}
+
 interface GuideData {
   __typename: "Guide";
   channel_id: string;
@@ -47,6 +53,7 @@ interface GuideData {
   type: string;
   semver: string;
   steps: GuideStepData[];
+  activation_location_rules: GuideActivationLocationRuleData[];
   inserted_at: string;
   updated_at: string;
 }
@@ -57,8 +64,14 @@ export interface KnockGuideStep extends GuideStepData {
   markAsArchived: () => void;
 }
 
+interface KnockGuideActivationLocationRule
+  extends GuideActivationLocationRuleData {
+  pattern: URLPattern;
+}
+
 export interface KnockGuide extends GuideData {
   steps: KnockGuideStep[];
+  activation_location_rules: KnockGuideActivationLocationRule[];
 }
 
 type GetGuidesQueryParams = {
@@ -133,6 +146,7 @@ type QueryStatus = {
 type StoreState = {
   guides: KnockGuide[];
   queries: Record<QueryKey, QueryStatus>;
+  location: string | undefined;
 };
 
 type QueryFilterParams = Pick<GetGuidesQueryParams, "type">;
@@ -147,6 +161,10 @@ export type TargetParams = {
   tenant?: string | undefined;
 };
 
+type ConstructorOpts = {
+  trackLocationFromWindow?: boolean;
+};
+
 export class KnockGuideClient {
   public store: Store<StoreState, (state: StoreState) => StoreState>;
 
@@ -156,14 +174,26 @@ export class KnockGuideClient {
   private socketChannelTopic: string;
   private socketEventTypes = ["guide.added", "guide.updated", "guide.removed"];
 
+  // Original history methods to monkey patch, or restore in cleanups.
+  private pushStateFn: History["pushState"] | undefined;
+  private replaceStateFn: History["replaceState"] | undefined;
+
   constructor(
     readonly knock: Knock,
     readonly channelId: string,
     readonly targetParams: TargetParams = {},
+    readonly options: ConstructorOpts = {},
   ) {
+    const { trackLocationFromWindow = true } = options;
+
+    const location = trackLocationFromWindow
+      ? window?.location.href
+      : undefined;
+
     this.store = new Store<StoreState>({
       guides: [],
       queries: {},
+      location,
     });
 
     // In server environments we might not have a socket connection.
@@ -171,9 +201,18 @@ export class KnockGuideClient {
     this.socket = maybeSocket;
     this.socketChannelTopic = `guides:${channelId}`;
 
+    if (trackLocationFromWindow) {
+      this.listenForLocationChangesFromWindow();
+    }
+
     this.knock.log("[Guide] Initialized a guide client");
   }
 
+  cleanup() {
+    this.unsubscribe();
+    this.removeEventListeners();
+  }
+
   async fetch(opts?: { filters?: QueryFilterParams }) {
     this.knock.failIfNotAuthenticated();
     this.knock.log("[Guide] Loading all eligible guides");
@@ -291,8 +330,6 @@ export class KnockGuideClient {
   //
 
   select(state: StoreState, filters: SelectFilterParams = {}) {
-    // TODO(KNO-7790): Need to evaluate activation rules also.
-
     return state.guides.filter((guide) => {
       if (filters.type && filters.type !== guide.type) {
         return false;
@@ -302,6 +339,42 @@ export class KnockGuideClient {
         return false;
       }
 
+      const locationRules = guide.activation_location_rules || [];
+
+      if (locationRules.length > 0 && state.location) {
+        const allowed = locationRules.reduce<boolean | undefined>(
+          (acc, rule) => {
+            // Any matched block rule prevails so no need to evaluate further
+            // as soon as there is one.
+            if (acc === false) return false;
+
+            // At this point we either have a matched allow rule (acc is true),
+            // or no matched rule found yet (acc is undefined).
+
+            switch (rule.directive) {
+              case "allow": {
+                // No need to evaluate more allow rules once we matched one
+                // since any matched allowed rule means allow.
+                if (acc === true) return true;
+
+                const matched = rule.pattern.test(state.location);
+                return matched ? true : undefined;
+              }
+
+              case "block": {
+                // Always test block rules (unless already matched to block)
+                // because they'd prevail over matched allow rules.
+                const matched = rule.pattern.test(state.location);
+                return matched ? false : acc;
+              }
+            }
+          },
+          undefined,
+        );
+
+        if (!allowed) return false;
+      }
+
       return true;
     });
   }
@@ -427,6 +500,14 @@ export class KnockGuideClient {
       return localStep;
     });
 
+    localGuide.activation_location_rules =
+      remoteGuide.activation_location_rules.map((rule) => {
+        return {
+          ...rule,
+          pattern: new URLPattern({ pathname: rule.pathname }),
+        };
+      });
+
     return localGuide as KnockGuide;
   }
 
@@ -538,4 +619,67 @@ export class KnockGuideClient {
       return { ...state, guides };
     });
   }
+
+  private handleLocationChange() {
+    const href = window.location.href;
+    if (this.store.state.location === href) return;
+
+    this.knock.log(`[Guide] Handle Location change: ${href}`);
+
+    this.store.setState((state) => ({ ...state, location: href }));
+  }
+
+  private listenForLocationChangesFromWindow() {
+    if (window?.history) {
+      // 1. Listen for browser back/forward button clicks.
+      window.addEventListener("popstate", this.handleLocationChange);
+
+      // 2. Listen for hash changes in case it's used for routing.
+      window.addEventListener("hashchange", this.handleLocationChange);
+
+      // 3. Monkey-patch history methods to catch programmatic navigation.
+      const pushStateFn = window.history.pushState;
+      const replaceStateFn = window.history.replaceState;
+
+      // Use setTimeout to allow the browser state to potentially settle.
+      window.history.pushState = new Proxy(pushStateFn, {
+        apply: (target, history, args) => {
+          Reflect.apply(target, history, args);
+          setTimeout(() => {
+            this.handleLocationChange();
+          }, 0);
+        },
+      });
+      window.history.replaceState = new Proxy(replaceStateFn, {
+        apply: (target, history, args) => {
+          Reflect.apply(target, history, args);
+          setTimeout(() => {
+            this.handleLocationChange();
+          }, 0);
+        },
+      });
+
+      // 4. Keep refs to the original handlers so we can restore during cleanup.
+      this.pushStateFn = pushStateFn;
+      this.replaceStateFn = replaceStateFn;
+    } else {
+      this.knock.log(
+        "[Guide] Unable to access the `window.history` object to detect location changes",
+      );
+    }
+  }
+
+  private removeEventListeners() {
+    window.removeEventListener("popstate", this.handleLocationChange);
+    window.removeEventListener("hashchange", this.handleLocationChange);
+
+    if (this.pushStateFn) {
+      window.history.pushState = this.pushStateFn;
+      this.pushStateFn = undefined;
+    }
+    if (this.replaceStateFn) {
+      window.history.replaceState = this.replaceStateFn;
+      this.replaceStateFn = undefined;
+    }
+  }
 }