@knocklabs/client 0.10.13 → 0.11.0-rc.0

package/src/clients/in-app-messages/message-client.ts

@@ -0,0 +1,271 @@
+import { GenericData } from "@knocklabs/types";
+import { nanoid } from "nanoid";
+
+import Knock from "../../knock";
+import { NetworkStatus, isRequestInFlight } from "../../networkStatus";
+import { MessageEngagementStatus } from "../messages/interfaces";
+
+import { InAppMessagesChannelClient } from "./channel-client";
+import { SocketEventPayload, SocketEventType } from "./socket-manager";
+import {
+  InAppMessage,
+  InAppMessagesClientOptions,
+  InAppMessagesResponse,
+  InAppMessagesStoreState,
+} from "./types";
+
+/**
+ * Manages realtime connection to in app messages service.
+ */
+export class InAppMessagesClient {
+  private knock: Knock;
+
+  public queryKey: string;
+  public referenceId: string;
+  public unsub?: () => void;
+
+  constructor(
+    readonly channelClient: InAppMessagesChannelClient,
+    readonly messageType: string,
+    readonly defaultOptions: InAppMessagesClientOptions = {},
+  ) {
+    this.defaultOptions = {
+      ...channelClient.defaultOptions,
+      ...defaultOptions,
+    };
+    this.knock = channelClient.knock;
+    this.queryKey = this.buildQueryKey(this.defaultOptions);
+    this.referenceId = nanoid();
+
+    this.knock.log(`[IAM] Initialized a client for message ${messageType}`);
+  }
+
+  // ----------------------------------------------
+  // Data fetching
+  // ----------------------------------------------
+  async fetch<
+    TContent extends GenericData = GenericData,
+    TData extends GenericData = GenericData,
+  >(): Promise<
+    | {
+        status: "ok";
+        data: InAppMessagesResponse<TContent, TData>;
+      }
+    | {
+        status: "error";
+        error: Error;
+      }
+    | undefined
+  > {
+    const params = this.defaultOptions;
+
+    this.queryKey = this.buildQueryKey(params);
+
+    const queryState = this.channelClient.store.state.queries[
+      this.queryKey
+    ] ?? {
+      loading: false,
+      networkStatus: NetworkStatus.ready,
+    };
+    const networkStatus = queryState.networkStatus;
+
+    // If there's an existing request in flight, then do nothing
+    if (networkStatus && isRequestInFlight(networkStatus)) {
+      return;
+    }
+
+    // Set the loading type based on the request type it is
+    this.channelClient.setQueryStatus(this.queryKey, {
+      networkStatus: NetworkStatus.loading,
+      loading: true,
+    });
+
+    try {
+      const response = await this.knock.user.getInAppMessages<TContent, TData>({
+        channelId: this.channelClient.channelId,
+        messageType: this.messageType,
+        params,
+      });
+
+      this.channelClient.setQueryResponse(this.queryKey, response);
+
+      return { data: response, status: "ok" };
+    } catch (error) {
+      this.channelClient.setQueryStatus(this.queryKey, {
+        networkStatus: NetworkStatus.error,
+        loading: false,
+      });
+
+      return {
+        status: "error",
+        error: error as Error,
+      };
+    }
+  }
+
+  getQueryInfoSelector<
+    TContent extends GenericData = GenericData,
+    TData extends GenericData = GenericData,
+  >(
+    state: InAppMessagesStoreState,
+  ): {
+    messages: InAppMessage<TContent, TData>[];
+    loading: boolean;
+    networkStatus: NetworkStatus;
+  } {
+    const queryInfo = state.queries[this.queryKey];
+    const messageIds = queryInfo?.data?.messageIds ?? [];
+
+    const messages = messageIds.reduce<InAppMessage<TContent, TData>[]>(
+      (messages, messageId) => {
+        const message = state.messages[messageId];
+        if (message) {
+          messages.push(message as InAppMessage<TContent, TData>);
+        }
+        return messages;
+      },
+      [],
+    );
+
+    return {
+      messages,
+      networkStatus: queryInfo?.networkStatus ?? NetworkStatus.ready,
+      loading: queryInfo?.loading ?? false,
+    };
+  }
+
+  // ----------------------------------------------
+  // Message engagement
+  // ----------------------------------------------
+  async markAsSeen(itemOrItems: InAppMessage | InAppMessage[]) {
+    const itemIds = this.getItemIds(itemOrItems);
+
+    this.channelClient.setMessageAttrs(itemIds, {
+      seen_at: new Date().toISOString(),
+    });
+
+    return this.makeStatusUpdate(itemOrItems, "seen");
+  }
+
+  async markAsUnseen(itemOrItems: InAppMessage | InAppMessage[]) {
+    const itemIds = this.getItemIds(itemOrItems);
+
+    this.channelClient.setMessageAttrs(itemIds, {
+      seen_at: null,
+    });
+
+    return this.makeStatusUpdate(itemOrItems, "unseen");
+  }
+
+  async markAsRead(itemOrItems: InAppMessage | InAppMessage[]) {
+    const itemIds = this.getItemIds(itemOrItems);
+
+    this.channelClient.setMessageAttrs(itemIds, {
+      read_at: new Date().toISOString(),
+    });
+
+    return this.makeStatusUpdate(itemOrItems, "read");
+  }
+
+  async markAsUnread(itemOrItems: InAppMessage | InAppMessage[]) {
+    const itemIds = this.getItemIds(itemOrItems);
+
+    this.channelClient.setMessageAttrs(itemIds, {
+      read_at: null,
+    });
+
+    return this.makeStatusUpdate(itemOrItems, "unread");
+  }
+
+  async markAsInteracted(
+    itemOrItems: InAppMessage | InAppMessage[],
+    metadata?: Record<string, string>,
+  ) {
+    const now = new Date().toISOString();
+    const itemIds = this.getItemIds(itemOrItems);
+
+    this.channelClient.setMessageAttrs(itemIds, {
+      read_at: now,
+      interacted_at: now,
+    });
+
+    return this.makeStatusUpdate(itemOrItems, "interacted", metadata);
+  }
+
+  async markAsArchived(itemOrItems: InAppMessage | InAppMessage[]) {
+    const itemIds = this.getItemIds(itemOrItems);
+
+    this.channelClient.setMessageAttrs(itemIds, {
+      archived_at: new Date().toISOString(),
+    });
+
+    return this.makeStatusUpdate(itemOrItems, "archived");
+  }
+
+  async markAsUnarchived(itemOrItems: InAppMessage | InAppMessage[]) {
+    const itemIds = this.getItemIds(itemOrItems);
+
+    this.channelClient.setMessageAttrs(itemIds, {
+      archived_at: null,
+    });
+
+    return this.makeStatusUpdate(itemOrItems, "unarchived");
+  }
+
+  private async makeStatusUpdate(
+    itemOrItems: InAppMessage | InAppMessage[],
+    type: MessageEngagementStatus | "unread" | "unseen" | "unarchived",
+    metadata?: Record<string, string>,
+  ) {
+    // Always treat items as a batch to use the corresponding batch endpoint
+    const itemIds = this.getItemIds(itemOrItems);
+
+    const result = await this.knock.messages.batchUpdateStatuses(
+      itemIds,
+      type,
+      { metadata },
+    );
+
+    return result;
+  }
+
+  // ----------------------------------------------
+  // Helpers
+  // ----------------------------------------------
+  private buildQueryKey(params: GenericData): string {
+    const baseKey = `/v1/users/${this.knock.userId}/in-app-messages/${this.channelClient.channelId}/${this.messageType}`;
+    const paramsString = new URLSearchParams(params).toString();
+    return paramsString ? `${baseKey}?${paramsString}` : baseKey;
+  }
+
+  subscribe() {
+    this.unsub = this.channelClient.subscribe(this);
+  }
+
+  unsubscribe() {
+    this.channelClient.unsubscribe(this);
+  }
+
+  // This is a callback function that will be invoked when a new socket event
+  // relevant for this message client is received (and if subscribed).
+  async handleSocketEvent(payload: SocketEventPayload) {
+    switch (payload.event) {
+      case SocketEventType.MessageCreated:
+        // TODO(KNO-7169): Explore using an in-app message in the socket event
+        // directly instead of re-fetching.
+        return await this.fetch();
+
+      default:
+        throw new Error(`Unhandled socket event: ${payload.event}`);
+    }
+  }
+
+  socketChannelTopic() {
+    return `in_app:${this.messageType}:${this.channelClient.channelId}:${this.knock.userId}`;
+  }
+
+  private getItemIds(itemOrItems: InAppMessage | InAppMessage[]): string[] {
+    const items = Array.isArray(itemOrItems) ? itemOrItems : [itemOrItems];
+    return items.map((item) => item.id);
+  }
+}

package/src/clients/in-app-messages/socket-manager.ts

@@ -0,0 +1,187 @@
+import { Store } from "@tanstack/store";
+import { Channel, Socket } from "phoenix";
+
+import { InAppMessagesClient } from "./message-client";
+import { InAppMessage, InAppMessagesClientOptions } from "./types";
+
+export enum SocketEventType {
+  MessageCreated = "message.created",
+}
+
+const SOCKET_EVENT_TYPES = [SocketEventType.MessageCreated];
+
+type ClientQueryParams = InAppMessagesClientOptions;
+
+// e.g. in_app:<message-type>:<channel_id>:<user_id>
+type ChannelTopic = string;
+
+// Unique reference id of an in-app message client
+type ClientReferenceId = string;
+
+type MessageCreatedEventPayload = {
+  event: SocketEventType.MessageCreated;
+  topic: string;
+  data: {
+    in_app_message: InAppMessage;
+  };
+};
+
+export type SocketEventPayload = MessageCreatedEventPayload;
+
+// "attn" field contains a list of client reference ids that should be notified
+// of a socket event.
+type WithAttn<P> = P & { attn: Array<ClientReferenceId> };
+
+type InAppMessageSocketInbox = Record<ClientReferenceId, SocketEventPayload>;
+
+/*
+ * Manages socket subscriptions for in-app messages, allowing multiple in-app
+ * message clients or components to listen for real time updates from the socket
+ * API via a single socket connection. It's expected to be instantiated once
+ * per an in-app channel.
+ */
+export class InAppMessageSocketManager {
+  // Mapping of live channels by topic. Note, there can be one or more in-app
+  // message client(s) that can subscribe.
+  private channels: Record<ChannelTopic, Channel>;
+
+  // Mapping of query params for each in-app message client, partitioned by its
+  // reference id, and grouped by channel topic. It's a double nested object
+  // that looks like:
+  //  {
+  //    "in_app:card:...": {
+  //      "ref-1": {
+  //        "workflow_key": "foo",
+  //      },
+  //      "ref-2": {
+  //        "workflow_key": "bar",
+  //      },
+  //    },
+  //    "in_app:banner:...": {
+  //      "ref-3": {
+  //        "workflow_key": "baz",
+  //      },
+  //    }
+  //  }
+  //
+  // Each time a new in-app message client joins a channel, we send all cumulated
+  // params such that the socket API can apply filtering rules and figure out
+  // which in-app message clients should be notified basd 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 in-app
+  // message clients that have subscribed.
+  private inbox: Store<
+    InAppMessageSocketInbox,
+    (cb: InAppMessageSocketInbox) => InAppMessageSocketInbox
+  >;
+
+  constructor(readonly socket: Socket) {
+    this.channels = {};
+    this.params = {};
+    this.inbox = new Store<InAppMessageSocketInbox>({});
+  }
+
+  join(iamClient: InAppMessagesClient) {
+    const topic = iamClient.socketChannelTopic();
+    const referenceId = iamClient.referenceId;
+    const params = iamClient.defaultOptions;
+
+    // Ensure a live socket connection if not yet connected.
+    if (!this.socket.isConnected()) {
+      this.socket.connect();
+    }
+
+    // If a new in-app message 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 in-app message clients that
+    // have subscribed for a given message type (and an in-app channel and a
+    // 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 client's params by its 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 in-app message client subscribe to the "inbox", so it can be
+    // notified when there's a new socket event that is relevant for the client.
+    const unsub = this.inbox.subscribe(() => {
+      const payload = this.inbox.state[referenceId];
+      if (!payload) return;
+
+      iamClient.handleSocketEvent(payload);
+    });
+
+    return unsub;
+  }
+
+  leave(iamClient: InAppMessagesClient) {
+    if (iamClient.unsub) {
+      iamClient.unsub();
+    }
+
+    const topic = iamClient.socketChannelTopic();
+    const referenceId = iamClient.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/in-app-messages/store.ts

@@ -0,0 +1,15 @@
+import { Store } from "@tanstack/store";
+
+import { InAppMessagesStoreState } from "./types";
+
+export type InAppMessagesStore = Store<
+  InAppMessagesStoreState,
+  (cb: InAppMessagesStoreState) => InAppMessagesStoreState
+>;
+
+export function createStore() {
+  return new Store<InAppMessagesStoreState>({
+    messages: {},
+    queries: {},
+  });
+}

package/src/clients/in-app-messages/types.ts

@@ -0,0 +1,79 @@
+import { GenericData, PageInfo, Tenant } from "@knocklabs/types";
+
+import { NetworkStatus } from "../../networkStatus";
+import { NotificationSource } from "../messages/interfaces";
+
+export interface InAppMessage<
+  TContent extends GenericData = GenericData,
+  TData extends GenericData = GenericData,
+  TTenantProperties = GenericData,
+> {
+  __cursor: string;
+  id: string;
+  message_type: string;
+  schema_variant: string;
+  schema_version: string;
+  content: TContent;
+  data: TData | null;
+  inserted_at: string;
+  updated_at: string;
+  seen_at: string | null;
+  read_at: string | null;
+  interacted_at: string | null;
+  archived_at: string | null;
+  link_clicked_at: string | null;
+  source: NotificationSource;
+  tenant: Tenant<TTenantProperties>;
+}
+
+export interface InAppMessagesResponse<
+  TContent extends GenericData = GenericData,
+  TData extends GenericData = GenericData,
+> {
+  entries: InAppMessage<TContent, TData>[];
+  pageInfo: PageInfo;
+}
+
+export interface InAppMessagesQueryInfo {
+  networkStatus: NetworkStatus;
+  loading: boolean;
+  data?: {
+    messageIds: string[];
+    pageInfo: PageInfo;
+  };
+}
+
+export interface InAppMessagesStoreState {
+  messages: Record<string, InAppMessage>;
+  queries: Record<string, InAppMessagesQueryInfo>;
+}
+
+export type InAppMessageEngagementStatus =
+  | "read"
+  | "unread"
+  | "seen"
+  | "unseen"
+  | "link_clicked"
+  | "link_unclicked"
+  | "interacted"
+  | "uninteracted";
+
+export interface InAppMessagesClientOptions {
+  order?: "asc" | "desc";
+  before?: string;
+  after?: string;
+  page_size?: number;
+  engagement_status?: InAppMessageEngagementStatus[];
+  // Optionally scope all requests to a particular tenant or tenants
+  tenant_id?: string | string[];
+  // Optionally scope to notifications from the given workflow or workflows
+  workflow_key?: string | string[];
+  // Optionally scope to notifications with any of the categories provided
+  workflow_categories?: string[];
+  // Optionally scope to a given archived status (defaults to `exclude`)
+  archived?: "include" | "exclude" | "only";
+  // Optionally scope all notifications that contain this argument as part of their trigger payload
+  // TODO(KNO-7140): This currently does not work because the API expects this
+  // to be a json string.
+  trigger_data?: GenericData;
+}

package/src/clients/preferences/interfaces.ts

@@ -1,7 +1,7 @@
 import { ChannelType } from "@knocklabs/types";
 
 export type ChannelTypePreferences = {
-  [K in ChannelType]?: boolean;
+  [_K in ChannelType]?: boolean;
 };
 
 export type WorkflowPreferenceSetting =

package/src/clients/users/index.ts

@@ -3,6 +3,7 @@ import { GenericData } from "@knocklabs/types";
 import { ApiResponse } from "../../api";
 import { ChannelData, User } from "../../interfaces";
 import Knock from "../../knock";
+import { InAppMessagesResponse } from "../in-app-messages";
 import {
   GetPreferencesOptions,
   PreferenceOptions,
@@ -10,7 +11,11 @@ import {
   SetPreferencesProperties,
 } from "../preferences/interfaces";
 
-import { GetChannelDataInput, SetChannelDataInput } from "./interfaces";
+import {
+  GetChannelDataInput,
+  GetInAppMessagesInput,
+  SetChannelDataInput,
+} from "./interfaces";
 
 const DEFAULT_PREFERENCE_SET_ID = "default";
 
@@ -100,6 +105,19 @@ class UserClient {
     return this.handleResponse<ChannelData<T>>(result);
   }
 
+  async getInAppMessages<
+    TContent extends GenericData = GenericData,
+    TData extends GenericData = GenericData,
+  >({ channelId, messageType, params }: GetInAppMessagesInput) {
+    const result = await this.instance.client().makeRequest({
+      method: "GET",
+      url: `/v1/users/${this.instance.userId}/in-app-messages/${channelId}/${messageType}`,
+      params,
+    });
+
+    return this.handleResponse<InAppMessagesResponse<TContent, TData>>(result);
+  }
+
   private handleResponse<T>(response: ApiResponse) {
     if (response.statusCode === "error") {
       throw new Error(response.error || response.body);

package/src/clients/users/interfaces.ts

@@ -1,5 +1,7 @@
 import { GenericData } from "@knocklabs/types";
 
+import { InAppMessagesClientOptions } from "../in-app-messages/types";
+
 export interface SetChannelDataInput {
   channelId: string;
   channelData: GenericData;
@@ -8,3 +10,9 @@ export interface SetChannelDataInput {
 export interface GetChannelDataInput {
   channelId: string;
 }
+
+export interface GetInAppMessagesInput {
+  channelId: string;
+  messageType: string;
+  params: InAppMessagesClientOptions;
+}

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./clients/slack/interfaces";
 export * from "./clients/users";
 export * from "./clients/users/interfaces";
 export * from "./clients/messages";
+export * from "./clients/in-app-messages";
 export * from "./clients/messages/interfaces";
 export * from "./networkStatus";