@knocklabs/client 0.15.1 → 0.16.0

package/src/clients/guide/helpers.ts

@@ -0,0 +1,98 @@
+import {
+  GuideData,
+  GuideGroupData,
+  KnockGuide,
+  SelectFilterParams,
+} from "./types";
+
+// Extends the map class to allow having metadata on it, which is used to record
+// the guide group context for the selection result (though currently only a
+// default global group is supported).
+export class SelectionResult<K = number, V = KnockGuide> extends Map<K, V> {
+  metadata: { guideGroup: GuideGroupData } | undefined;
+
+  constructor() {
+    super();
+  }
+}
+
+export const formatFilters = (filters: SelectFilterParams = {}) => {
+  return [
+    filters.key && `key=${filters.key}`,
+    filters.type && `type=${filters.type}`,
+  ]
+    .filter((x) => x)
+    .join(", ");
+};
+
+export const byKey = <T extends { key: string }>(items: T[]) => {
+  return items.reduce((acc, item) => ({ ...acc, [item.key]: item }), {});
+};
+
+const sortGuides = <T extends GuideData>(guides: T[]) => {
+  return [...guides].sort(
+    (a, b) =>
+      new Date(a.inserted_at).getTime() - new Date(b.inserted_at).getTime(),
+  );
+};
+
+// Default global guide group key.
+export const DEFAULT_GROUP_KEY = "default";
+
+// Prefixed with a special char $ to distinguish from an actual default group.
+const MOCK_DEFAULT_GROUP_KEY = "$default";
+
+// Build a notional default group to fall back on in case there is none, only
+// for safety as there should always be a default guide group created.
+export const mockDefaultGroup = (entries: GuideData[] = []) => {
+  const now = new Date();
+
+  return {
+    __typename: "GuideGroup",
+    key: MOCK_DEFAULT_GROUP_KEY,
+    display_sequence: sortGuides(entries).map((g) => g.key),
+    display_interval: null,
+    inserted_at: now.toISOString(),
+    updated_at: now.toISOString(),
+  } as GuideGroupData;
+};
+
+export const findDefaultGroup = (guideGroups: GuideGroupData[]) =>
+  guideGroups.find(
+    (group) =>
+      group.key === DEFAULT_GROUP_KEY || group.key === MOCK_DEFAULT_GROUP_KEY,
+  );
+
+// Checks whether we are currently throttled (inside a "throttle window").
+// A throttle window opens when a user dismisses (archives) a guide, and lasts
+// for the configured display interval of the guide group used (currently only
+// the default global group).
+export const checkIfThrottled = (
+  throttleWindowStartedAtTs: string,
+  windowDurationInSeconds: number,
+) => {
+  // 1. Parse the given timestamp string into a Date object.
+  // Date.parse() handles ISO 8601 strings correctly and returns milliseconds
+  // since epoch. This inherently handles timezones by converting everything to
+  // a universal time representation (UTC).
+  const throttleWindowStartDate = new Date(throttleWindowStartedAtTs);
+
+  // Check if the given throttle window start timestamp string was valid, and
+  // if not disregard.
+  if (isNaN(throttleWindowStartDate.getTime())) {
+    return false;
+  }
+
+  // 2. Calculate the throttle window end time in milliseconds by adding the
+  // duration to the throttle window start time.
+  const throttleWindowEndInMilliseconds =
+    throttleWindowStartDate.getTime() + windowDurationInSeconds * 1000;
+
+  // 3. Get the current timestamp in milliseconds since epoch.
+  const currentTimeInMilliseconds = new Date().getTime();
+
+  // 4. Compare the current timestamp with the calculated future timestamp.
+  // Both are in milliseconds since epoch (UTC), so direct comparison is
+  // accurate regardless of local timezones.
+  return currentTimeInMilliseconds <= throttleWindowEndInMilliseconds;
+};

package/src/clients/guide/index.ts

@@ -4,4 +4,4 @@ export type {
   KnockGuideStep,
   TargetParams as KnockGuideTargetParams,
   SelectFilterParams as KnockGuideFilterParams,
-} from "./client";
+} from "./types";

package/src/clients/guide/types.ts

@@ -0,0 +1,206 @@
+import { GenericData } from "@knocklabs/types";
+
+//
+// Fetch guides API
+//
+
+export 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;
+}
+
+export interface GuideStepData {
+  ref: string;
+  schema_key: string;
+  schema_semver: string;
+  schema_variant_key: string;
+  message: StepMessageState;
+  // eslint-disable-next-line
+  content: any;
+}
+
+interface GuideActivationLocationRuleData {
+  directive: "allow" | "block";
+  pathname: string;
+}
+
+export interface GuideData {
+  __typename: "Guide";
+  channel_id: string;
+  id: string;
+  key: string;
+  type: string;
+  semver: string;
+  steps: GuideStepData[];
+  activation_location_rules: GuideActivationLocationRuleData[];
+  bypass_global_group_limit: boolean;
+  inserted_at: string;
+  updated_at: string;
+}
+
+export interface GuideGroupData {
+  __typename: "GuideGroup";
+  key: string;
+  display_sequence: Array<GuideData["key"]>;
+  display_sequence_unthrottled: Array<GuideData["key"]> | null;
+  display_sequence_throttled: Array<GuideData["key"]> | null;
+  display_interval: number | null;
+  inserted_at: string;
+  updated_at: string;
+}
+
+export type GetGuidesQueryParams = {
+  data?: string;
+  tenant?: string;
+  type?: string;
+};
+
+export type GetGuidesResponse = {
+  entries: GuideData[];
+  guide_groups: GuideGroupData[];
+  guide_group_display_logs: Record<GuideGroupData["key"], string>;
+};
+
+//
+// Engagement actions API
+//
+
+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;
+};
+
+export type MarkAsSeenParams = GuideEngagementEventBaseParams & {
+  // Rendered step content seen by the recipient
+  content: GenericData;
+  // Target params
+  data?: GenericData;
+  tenant?: string;
+};
+export type MarkAsInteractedParams = GuideEngagementEventBaseParams;
+export type MarkAsArchivedParams = GuideEngagementEventBaseParams & {
+  unthrottled?: boolean;
+};
+
+export type MarkGuideAsResponse = {
+  status: "ok";
+};
+
+//
+// Socket events
+//
+
+type SocketEventType =
+  | "guide.added"
+  | "guide.updated"
+  | "guide.removed"
+  | "guide_group.added"
+  | "guide_group.updated";
+
+type SocketEventPayload<E extends SocketEventType, D> = {
+  topic: string;
+  event: E;
+  data: D;
+};
+
+export type GuideAddedEvent = SocketEventPayload<
+  "guide.added",
+  { guide: GuideData; eligible: true }
+>;
+
+export type GuideUpdatedEvent = SocketEventPayload<
+  "guide.updated",
+  { guide: GuideData; eligible: boolean }
+>;
+
+export type GuideRemovedEvent = SocketEventPayload<
+  "guide.removed",
+  { guide: Pick<GuideData, "key"> }
+>;
+
+export type GuideGroupAddedEvent = SocketEventPayload<
+  "guide_group.added",
+  { guide_group: GuideGroupData }
+>;
+
+export type GuideGroupUpdatedEvent = SocketEventPayload<
+  "guide_group.updated",
+  { guide_group: GuideGroupData }
+>;
+
+export type GuideSocketEvent =
+  | GuideAddedEvent
+  | GuideUpdatedEvent
+  | GuideRemovedEvent
+  | GuideGroupAddedEvent
+  | GuideGroupUpdatedEvent;
+
+//
+// Guide client
+//
+
+export interface KnockGuideStep extends GuideStepData {
+  markAsSeen: () => void;
+  markAsInteracted: (params?: { metadata?: GenericData }) => void;
+  markAsArchived: () => void;
+}
+
+interface KnockGuideActivationLocationRule
+  extends GuideActivationLocationRuleData {
+  pattern: URLPattern;
+}
+
+export interface KnockGuide extends GuideData {
+  steps: KnockGuideStep[];
+  activation_location_rules: KnockGuideActivationLocationRule[];
+  getStep: () => KnockGuideStep | undefined;
+}
+
+type QueryKey = string;
+
+export type QueryStatus = {
+  status: "loading" | "ok" | "error";
+  error?: Error;
+};
+
+export type StoreState = {
+  guideGroups: GuideGroupData[];
+  guideGroupDisplayLogs: Record<GuideGroupData["key"], string>;
+  guides: Record<KnockGuide["key"], KnockGuide>;
+  queries: Record<QueryKey, QueryStatus>;
+  location: string | undefined;
+  counter: number;
+};
+
+export type QueryFilterParams = Pick<GetGuidesQueryParams, "type">;
+
+export type SelectFilterParams = {
+  key?: string;
+  type?: string;
+};
+
+export type TargetParams = {
+  data?: GenericData | undefined;
+  tenant?: string | undefined;
+};
+
+export type ConstructorOpts = {
+  trackLocationFromWindow?: boolean;
+  orderResolutionDuration?: number;
+  throttleCheckInterval?: number;
+};
+
+export type GroupStage = {
+  status: "open" | "closed" | "patch";
+  ordered: Array<KnockGuide["key"]>;
+  resolved?: KnockGuide["key"];
+  timeoutId: ReturnType<typeof setTimeout> | null;
+};

package/src/clients/users/index.ts

@@ -3,10 +3,8 @@ import { GenericData } from "@knocklabs/types";
 import { ApiResponse } from "../../api";
 import { ChannelData, User } from "../../interfaces";
 import Knock from "../../knock";
-import {
-  GuideEngagementEventBaseParams,
-  guidesApiRootPath,
-} from "../guide/client";
+import { guidesApiRootPath } from "../guide/client";
+import { GuideEngagementEventBaseParams } from "../guide/types";
 import {
   GetPreferencesOptions,
   PreferenceOptions,