@knocklabs/client 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knocklabs/client",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "The clientside library for interacting with Knock",
   "homepage": "https://github.com/knocklabs/javascript/tree/main/packages/client",
   "author": "@knocklabs",
@@ -56,7 +56,7 @@
     "@babel/preset-typescript": "^7.26.0",
     "@types/jsonwebtoken": "^9.0.9",
     "@typescript-eslint/eslint-plugin": "^8.19.1",
-    "@typescript-eslint/parser": "^8.24.0",
+    "@typescript-eslint/parser": "^8.27.0",
     "cross-env": "^7.0.3",
     "crypto": "^1.0.1",
     "eslint": "^8.56.0",
@@ -69,10 +69,11 @@
     "vitest": "^2.1.8"
   },
   "dependencies": {
-    "@babel/runtime": "^7.26.0",
+    "@babel/runtime": "^7.27.0",
     "@knocklabs/types": "^0.1.5",
+    "@tanstack/store": "^0.5.5",
     "@types/phoenix": "^1.6.6",
-    "axios": "^1.8.1",
+    "axios": "^1.8.4",
     "axios-retry": "^4.5.0",
     "eventemitter2": "^6.4.5",
     "jwt-decode": "^4.0.0",

package/src/clients/feed/feed.ts

@@ -28,6 +28,7 @@ import {
   FeedRealTimeCallback,
   FeedStoreState,
 } from "./types";
+import { mergeDateRangeParams } from "./utils";
 
 // Default options to apply
 const feedClientDefaults: Pick<FeedClientOptions, "archived"> = {
@@ -59,8 +60,10 @@ class Feed {
     this.userFeedId = this.buildUserFeedId();
     this.store = createStore();
     this.broadcaster = new EventEmitter({ wildcard: true, delimiter: "." });
-    this.defaultOptions = { ...feedClientDefaults, ...options };
-
+    this.defaultOptions = {
+      ...feedClientDefaults,
+      ...mergeDateRangeParams(options),
+    };
     this.knock.log(`[Feed] Initialized a feed on channel ${feedId}`);
 
     // Attempt to setup a realtime connection (does not join)
@@ -490,49 +493,19 @@ class Feed {
     // Always include the default params, if they have been set
     const queryParams = {
       ...this.defaultOptions,
-      ...options,
+      ...mergeDateRangeParams(options),
       // Unset options that should not be sent to the API
       __loadingType: undefined,
       __fetchSource: undefined,
       __experimentalCrossBrowserUpdates: undefined,
       auto_manage_socket_connection: undefined,
       auto_manage_socket_connection_delay: undefined,
-      inserted_at_date_range: undefined,
     };
 
-    // If the user has set a date range, transform it to the backend's expected format
-    const dateRange = options.inserted_at_date_range;
-    let finalQueryParams = { ...queryParams };
-
-    if (dateRange) {
-      // Create a properly typed object for our date filter parameters
-      const dateRangeParams: Record<string, string> = {};
-
-      // Determine which operators to use based on the inclusive flag
-      const isInclusive = dateRange.inclusive ?? false;
-
-      // For start date: use gte if inclusive, gt if not
-      if (dateRange.start) {
-        const startOperator = isInclusive
-          ? "inserted_at.gte"
-          : "inserted_at.gt";
-        dateRangeParams[startOperator] = dateRange.start;
-      }
-
-      // For end date: use lte if inclusive, lt if not
-      if (dateRange.end) {
-        const endOperator = isInclusive ? "inserted_at.lte" : "inserted_at.lt";
-        dateRangeParams[endOperator] = dateRange.end;
-      }
-
-      // Create a new object combining queryParams and dateRangeParams
-      finalQueryParams = { ...queryParams, ...dateRangeParams };
-    }
-
     const result = await this.knock.client().makeRequest({
       method: "GET",
       url: `/v1/users/${this.knock.userId}/feeds/${this.feedId}`,
-      params: finalQueryParams,
+      params: queryParams,
     });
 
     if (result.statusCode === "error" || !result.body) {

package/src/clients/feed/utils.ts

@@ -1,4 +1,4 @@
-import { FeedItem } from "./interfaces";
+import { FeedClientOptions, FeedItem } from "./interfaces";
 
 export function deduplicateItems(items: FeedItem[]): FeedItem[] {
   const seen: Record<string, boolean> = {};
@@ -21,3 +21,30 @@ export function sortItems(items: FeedItem[]) {
     );
   });
 }
+
+export function mergeDateRangeParams(options: FeedClientOptions) {
+  const { inserted_at_date_range, ...rest } = options;
+
+  if (!inserted_at_date_range) {
+    return rest;
+  }
+
+  const dateRangeParams: Record<string, string> = {};
+
+  // Determine which operators to use based on the inclusive flag
+  const isInclusive = inserted_at_date_range.inclusive ?? false;
+
+  // For start date: use gte if inclusive, gt if not
+  if (inserted_at_date_range.start) {
+    const startOperator = isInclusive ? "inserted_at.gte" : "inserted_at.gt";
+    dateRangeParams[startOperator] = inserted_at_date_range.start;
+  }
+
+  // For end date: use lte if inclusive, lt if not
+  if (inserted_at_date_range.end) {
+    const endOperator = isInclusive ? "inserted_at.lte" : "inserted_at.lt";
+    dateRangeParams[endOperator] = inserted_at_date_range.end;
+  }
+
+  return { ...rest, ...dateRangeParams };
+}

package/src/clients/guide/client.ts

@@ -0,0 +1,541 @@
+import { GenericData } from "@knocklabs/types";
+import { Store } from "@tanstack/store";
+import { Channel, Socket } from "phoenix";
+
+import Knock from "../../knock";
+
+const sortGuides = (guides: KnockGuide[]) => {
+  return [...guides].sort(
+    (a, b) =>
+      b.priority - a.priority ||
+      new Date(b.inserted_at).getTime() - new Date(a.inserted_at).getTime(),
+  );
+};
+
+//
+// Guides API (via User client)
+//
+
+export const guidesApiRootPath = (userId: string | undefined | null) =>
+  `/v1/users/${userId}/guides`;
+
+interface StepMessageState {
+  id: string;
+  seen_at: string | null;
+  read_at: string | null;
+  interacted_at: string | null;
+  archived_at: string | null;
+  link_clicked_at: string | null;
+}
+
+interface GuideStepData {
+  ref: string;
+  schema_key: string;
+  schema_semver: string;
+  schema_variant_key: string;
+  message: StepMessageState;
+  // eslint-disable-next-line
+  content: any;
+}
+
+interface GuideData {
+  __typename: "Guide";
+  channel_id: string;
+  id: string;
+  key: string;
+  priority: number;
+  type: string;
+  semver: string;
+  steps: GuideStepData[];
+  inserted_at: string;
+  updated_at: string;
+}
+
+export interface KnockGuideStep extends GuideStepData {
+  markAsSeen: () => void;
+  markAsInteracted: (params?: { metadata?: GenericData }) => void;
+  markAsArchived: () => void;
+}
+
+export interface KnockGuide extends GuideData {
+  steps: KnockGuideStep[];
+}
+
+type GetGuidesQueryParams = {
+  data?: string;
+  tenant?: string;
+  type?: string;
+};
+
+type GetGuidesResponse = {
+  entries: GuideData[];
+};
+
+export type GuideEngagementEventBaseParams = {
+  // Base params required for all engagement update events
+  message_id: string;
+  channel_id: string;
+  guide_key: string;
+  guide_id: string;
+  guide_step_ref: string;
+};
+
+type MarkAsSeenParams = GuideEngagementEventBaseParams & {
+  // Rendered step content seen by the recipient
+  content: GenericData;
+  // Target params
+  data?: GenericData;
+  tenant?: string;
+};
+type MarkAsInteractedParams = GuideEngagementEventBaseParams;
+type MarkAsArchivedParams = GuideEngagementEventBaseParams;
+
+type MarkGuideAsResponse = {
+  status: "ok";
+};
+
+type SocketEventType = "guide.added" | "guide.updated" | "guide.removed";
+
+type SocketEventPayload<E extends SocketEventType, D> = {
+  topic: string;
+  event: E;
+  data: D;
+};
+
+type GuideAddedEvent = SocketEventPayload<
+  "guide.added",
+  { guide: GuideData; eligible: true }
+>;
+
+type GuideUpdatedEvent = SocketEventPayload<
+  "guide.updated",
+  { guide: GuideData; eligible: boolean }
+>;
+
+type GuideRemovedEvent = SocketEventPayload<
+  "guide.removed",
+  { guide: Pick<GuideData, "key"> }
+>;
+
+type GuideSocketEvent = GuideAddedEvent | GuideUpdatedEvent | GuideRemovedEvent;
+
+//
+// Guides client
+//
+
+type QueryKey = string;
+
+type QueryStatus = {
+  status: "loading" | "ok" | "error";
+  error?: Error;
+};
+
+type StoreState = {
+  guides: KnockGuide[];
+  queries: Record<QueryKey, QueryStatus>;
+};
+
+type QueryFilterParams = Pick<GetGuidesQueryParams, "type">;
+
+export type SelectFilterParams = {
+  key?: string;
+  type?: string;
+};
+
+export type TargetParams = {
+  data?: GenericData | undefined;
+  tenant?: string | undefined;
+};
+
+export class KnockGuideClient {
+  public store: Store<StoreState, (state: StoreState) => StoreState>;
+
+  // Phoenix channels for real time guide updates over websocket
+  private socket: Socket | undefined;
+  private socketChannel: Channel | undefined;
+  private socketChannelTopic: string;
+  private socketEventTypes = ["guide.added", "guide.updated", "guide.removed"];
+
+  constructor(
+    readonly knock: Knock,
+    readonly channelId: string,
+    readonly targetParams: TargetParams = {},
+  ) {
+    this.store = new Store<StoreState>({
+      guides: [],
+      queries: {},
+    });
+
+    // In server environments we might not have a socket connection.
+    const { socket: maybeSocket } = this.knock.client();
+    this.socket = maybeSocket;
+    this.socketChannelTopic = `guides:${channelId}`;
+
+    this.knock.log("[Guide] Initialized a guide client");
+  }
+
+  async fetch(opts?: { filters?: QueryFilterParams }) {
+    this.knock.failIfNotAuthenticated();
+    this.knock.log("[Guide] Loading all eligible guides");
+
+    const queryParams = this.buildQueryParams(opts?.filters);
+    const queryKey = this.formatQueryKey(queryParams);
+
+    // If already fetched before, then noop.
+    const maybeQueryStatus = this.store.state.queries[queryKey];
+    if (maybeQueryStatus) {
+      return maybeQueryStatus;
+    }
+
+    // Mark this query status as loading.
+    this.store.setState((state) => ({
+      ...state,
+      queries: { ...state.queries, [queryKey]: { status: "loading" } },
+    }));
+
+    let queryStatus: QueryStatus;
+    try {
+      const data = await this.knock.user.getGuides<
+        GetGuidesQueryParams,
+        GetGuidesResponse
+      >(this.channelId, queryParams);
+      queryStatus = { status: "ok" };
+
+      this.store.setState((state) => ({
+        ...state,
+        // For now assume a single fetch to get all eligible guides. When/if
+        // we implement incremental loads, then this will need to be a merge
+        // and sort operation.
+        guides: data.entries.map((g) => this.localCopy(g)),
+        queries: { ...state.queries, [queryKey]: queryStatus },
+      }));
+    } catch (e) {
+      queryStatus = { status: "error", error: e as Error };
+
+      this.store.setState((state) => ({
+        ...state,
+        queries: { ...state.queries, [queryKey]: queryStatus },
+      }));
+    }
+
+    return queryStatus;
+  }
+
+  subscribe() {
+    if (!this.socket) return;
+    this.knock.failIfNotAuthenticated();
+    this.knock.log("[Guide] Subscribing to real time updates");
+
+    // Ensure a live socket connection if not yet connected.
+    if (!this.socket.isConnected()) {
+      this.socket.connect();
+    }
+
+    // If there's an existing connected channel, then disconnect.
+    if (this.socketChannel) {
+      this.unsubscribe();
+    }
+
+    // Join the channel topic and subscribe to supported events.
+    const params = { ...this.targetParams, user_id: this.knock.userId };
+    const newChannel = this.socket.channel(this.socketChannelTopic, params);
+
+    for (const eventType of this.socketEventTypes) {
+      newChannel.on(eventType, (payload) => this.handleSocketEvent(payload));
+    }
+
+    if (["closed", "errored"].includes(newChannel.state)) {
+      newChannel.join();
+    }
+
+    // Track the joined channel.
+    this.socketChannel = newChannel;
+  }
+
+  unsubscribe() {
+    if (!this.socketChannel) return;
+    this.knock.log("[Guide] Unsubscribing from real time updates");
+
+    // Unsubscribe from the socket events and leave the channel.
+    for (const eventType of this.socketEventTypes) {
+      this.socketChannel.off(eventType);
+    }
+    this.socketChannel.leave();
+
+    // Unset the channel.
+    this.socketChannel = undefined;
+  }
+
+  private handleSocketEvent(payload: GuideSocketEvent) {
+    const { event, data } = payload;
+
+    switch (event) {
+      case "guide.added":
+        return this.addGuide(payload);
+
+      case "guide.updated":
+        return data.eligible
+          ? this.replaceOrAddGuide(payload)
+          : this.removeGuide(payload);
+
+      case "guide.removed":
+        return this.removeGuide(payload);
+
+      default:
+        return;
+    }
+  }
+
+  //
+  // Store selector
+  //
+
+  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;
+      }
+
+      if (filters.key && filters.key !== guide.key) {
+        return false;
+      }
+
+      return true;
+    });
+  }
+
+  //
+  // Engagement event handlers
+  //
+  // Make an optimistic update on the client side first, then send an engagement
+  // event to the backend.
+  //
+
+  async markAsSeen(guide: GuideData, step: GuideStepData) {
+    this.knock.log(
+      `[Guide] Marking as seen (Guide key: ${guide.key}, Step ref:${step.ref})`,
+    );
+
+    const updatedStep = this.setStepMessageAttrs(guide.key, step.ref, {
+      seen_at: new Date().toISOString(),
+    });
+    if (!updatedStep) return;
+
+    const params = {
+      ...this.buildEngagementEventBaseParams(guide, updatedStep),
+      content: updatedStep.content,
+      data: this.targetParams.data,
+      tenant: this.targetParams.tenant,
+    };
+
+    this.knock.user.markGuideStepAs<MarkAsSeenParams, MarkGuideAsResponse>(
+      "seen",
+      params,
+    );
+
+    return updatedStep;
+  }
+
+  async markAsInteracted(
+    guide: GuideData,
+    step: GuideStepData,
+    metadata?: GenericData,
+  ) {
+    this.knock.log(
+      `[Guide] Marking as interacted (Guide key: ${guide.key}, Step ref:${step.ref})`,
+    );
+
+    const ts = new Date().toISOString();
+    const updatedStep = this.setStepMessageAttrs(guide.key, step.ref, {
+      read_at: ts,
+      interacted_at: ts,
+    });
+    if (!updatedStep) return;
+
+    const params = {
+      ...this.buildEngagementEventBaseParams(guide, updatedStep),
+      metadata,
+    };
+
+    this.knock.user.markGuideStepAs<
+      MarkAsInteractedParams,
+      MarkGuideAsResponse
+    >("interacted", params);
+
+    return updatedStep;
+  }
+
+  async markAsArchived(guide: GuideData, step: GuideStepData) {
+    this.knock.log(
+      `[Guide] Marking as archived (Guide key: ${guide.key}, Step ref:${step.ref})`,
+    );
+
+    const updatedStep = this.setStepMessageAttrs(guide.key, step.ref, {
+      archived_at: new Date().toISOString(),
+    });
+    if (!updatedStep) return;
+
+    const params = this.buildEngagementEventBaseParams(guide, updatedStep);
+
+    this.knock.user.markGuideStepAs<MarkAsArchivedParams, MarkGuideAsResponse>(
+      "archived",
+      params,
+    );
+
+    return updatedStep;
+  }
+
+  //
+  // Helpers
+  //
+
+  private localCopy(remoteGuide: GuideData) {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this;
+
+    // Build a local copy with helper methods added.
+    const localGuide = { ...remoteGuide };
+
+    localGuide.steps = remoteGuide.steps.map(({ message, ...rest }) => {
+      const localStep = {
+        ...rest,
+        message: { ...message },
+        markAsSeen() {
+          // Send a seen event if it has not been previously seen.
+          if (this.message.seen_at) return;
+          return self.markAsSeen(localGuide, this);
+        },
+        markAsInteracted({ metadata }: { metadata?: GenericData } = {}) {
+          // Always send an interaction event through.
+          return self.markAsInteracted(localGuide, this, metadata);
+        },
+        markAsArchived() {
+          // Send an archived event if it has not been previously archived.
+          if (this.message.archived_at) return;
+          return self.markAsArchived(localGuide, this);
+        },
+      };
+
+      // Bind all engagement action handler methods to the local step object so
+      // they can operate on itself.
+      localStep.markAsSeen = localStep.markAsSeen.bind(localStep);
+      localStep.markAsInteracted = localStep.markAsInteracted.bind(localStep);
+      localStep.markAsArchived = localStep.markAsArchived.bind(localStep);
+
+      return localStep;
+    });
+
+    return localGuide as KnockGuide;
+  }
+
+  private buildQueryParams(filterParams: QueryFilterParams = {}) {
+    // Combine the target params with the given filter params.
+    const combinedParams = { ...this.targetParams, ...filterParams };
+
+    // Prune out any keys that have an undefined or null value.
+    let params = Object.fromEntries(
+      Object.entries(combinedParams).filter(
+        ([_k, v]) => v !== undefined && v !== null,
+      ),
+    );
+
+    // Encode target data as a JSON string, if provided.
+    params = params.data
+      ? { ...params, data: JSON.stringify(params.data) }
+      : params;
+
+    return params as GetGuidesQueryParams;
+  }
+
+  private formatQueryKey(queryParams: GenericData) {
+    const sortedKeys = Object.keys(queryParams).sort();
+
+    const queryStr = sortedKeys
+      .map(
+        (key) =>
+          `${encodeURIComponent(key)}=${encodeURIComponent(queryParams[key])}`,
+      )
+      .join("&");
+
+    const basePath = guidesApiRootPath(this.knock.userId);
+    return queryStr ? `${basePath}?${queryStr}` : basePath;
+  }
+
+  private setStepMessageAttrs(
+    guideKey: string,
+    stepRef: string,
+    attrs: Partial<StepMessageState>,
+  ) {
+    let updatedStep: KnockGuideStep | undefined;
+
+    this.store.setState((state) => {
+      const guides = state.guides.map((guide) => {
+        if (guide.key !== guideKey) return guide;
+
+        const steps = guide.steps.map((step) => {
+          if (step.ref !== stepRef) return step;
+
+          // Mutate in place and maintain the same obj ref so to make it easier
+          // to use in hook deps.
+          step.message = { ...step.message, ...attrs };
+          updatedStep = step;
+
+          return step;
+        });
+        return { ...guide, steps };
+      });
+      return { ...state, guides };
+    });
+
+    return updatedStep;
+  }
+
+  private buildEngagementEventBaseParams(
+    guide: GuideData,
+    step: GuideStepData,
+  ) {
+    return {
+      message_id: step.message.id,
+      channel_id: guide.channel_id,
+      guide_key: guide.key,
+      guide_id: guide.id,
+      guide_step_ref: step.ref,
+    };
+  }
+
+  private addGuide({ data }: GuideAddedEvent) {
+    const guide = this.localCopy(data.guide);
+
+    this.store.setState((state) => {
+      return { ...state, guides: sortGuides([...state.guides, guide]) };
+    });
+  }
+
+  private replaceOrAddGuide({ data }: GuideUpdatedEvent) {
+    const guide = this.localCopy(data.guide);
+
+    this.store.setState((state) => {
+      let replaced = false;
+
+      const guides = state.guides.map((g) => {
+        if (g.key !== guide.key) return g;
+        replaced = true;
+        return guide;
+      });
+
+      return {
+        ...state,
+        guides: replaced ? sortGuides(guides) : sortGuides([...guides, guide]),
+      };
+    });
+  }
+
+  private removeGuide({ data }: GuideUpdatedEvent | GuideRemovedEvent) {
+    this.store.setState((state) => {
+      const guides = state.guides.filter((g) => g.key !== data.guide.key);
+      return { ...state, guides };
+    });
+  }
+}

package/src/clients/guide/index.ts

@@ -0,0 +1,7 @@
+export { KnockGuideClient } from "./client";
+export type {
+  KnockGuide,
+  KnockGuideStep,
+  TargetParams as KnockGuideTargetParams,
+  SelectFilterParams as KnockGuideFilterParams,
+} from "./client";