feat: add support for "simple" activation url rules (#731)

Author: thomaswhyyou

.changeset/lemon-monkeys-hunt.md

@@ -0,0 +1,6 @@
+---
+"@knocklabs/client": patch
+"@knocklabs/react": patch
+---
+
+add support for activation url rules in guide client

packages/client/src/clients/guide/client.ts

@@ -13,6 +13,9 @@ import {
   findDefaultGroup,
   formatFilters,
   mockDefaultGroup,
+  newUrl,
+  predicateUrlPatterns,
+  predicateUrlRules,
 } from "./helpers";
 import {
   Any,
@@ -144,36 +147,17 @@ const predicate = (
     return false;
   }
 
-  const locationRules = guide.activation_location_rules || [];
+  const url = location ? newUrl(location) : undefined;
 
-  if (locationRules.length > 0 && 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(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(location);
-          return matched ? false : acc;
-        }
-      }
-    }, undefined);
+  const urlRules = guide.activation_url_rules || [];
+  const urlPatterns = guide.activation_url_patterns || [];
 
+  // A guide can have either activation url rules XOR url patterns, but not both.
+  if (url && urlRules.length > 0) {
+    const allowed = predicateUrlRules(url, urlRules);
+    if (!allowed) return false;
+  } else if (url && urlPatterns.length > 0) {
+    const allowed = predicateUrlPatterns(url, urlPatterns);
     if (!allowed) return false;
   }
 
@@ -814,8 +798,8 @@ export class KnockGuideClient {
       return localStep;
     });
 
-    localGuide.activation_location_rules =
-      remoteGuide.activation_location_rules.map((rule) => {
+    localGuide.activation_url_patterns =
+      remoteGuide.activation_url_patterns.map((rule) => {
         return {
           ...rule,
           pattern: new URLPattern({ pathname: rule.pathname }),

packages/client/src/clients/guide/helpers.ts

@@ -1,7 +1,9 @@
 import {
+  GuideActivationUrlRuleData,
   GuideData,
   GuideGroupData,
   KnockGuide,
+  KnockGuideActivationUrlPattern,
   SelectFilterParams,
 } from "./types";
 
@@ -96,3 +98,100 @@ export const checkIfThrottled = (
   // accurate regardless of local timezones.
   return currentTimeInMilliseconds <= throttleWindowEndInMilliseconds;
 };
+
+// Safely parse and build a new URL object.
+export const newUrl = (location: string) => {
+  try {
+    return new URL(location);
+  } catch {
+    return undefined;
+  }
+};
+
+// Evaluates whether the given location url satisfies the url rule.
+export const evaluateUrlRule = (
+  url: URL,
+  urlRule: GuideActivationUrlRuleData,
+) => {
+  if (urlRule.variable === "pathname") {
+    if (urlRule.operator === "equal_to") {
+      const argument = urlRule.argument.startsWith("/")
+        ? urlRule.argument
+        : `/${urlRule.argument}`;
+
+      return argument === url.pathname;
+    }
+
+    if (urlRule.operator === "contains") {
+      return url.pathname.includes(urlRule.argument);
+    }
+
+    return false;
+  }
+
+  return false;
+};
+
+export const predicateUrlRules = (
+  url: URL,
+  urlRules: GuideActivationUrlRuleData[],
+) => {
+  return urlRules.reduce<boolean | undefined>((acc, urlRule) => {
+    // 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 (urlRule.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 = evaluateUrlRule(url, urlRule);
+        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 = evaluateUrlRule(url, urlRule);
+        return matched ? false : acc;
+      }
+    }
+  }, undefined);
+};
+
+export const predicateUrlPatterns = (
+  url: URL,
+  urlPatterns: KnockGuideActivationUrlPattern[],
+) => {
+  return urlPatterns.reduce<boolean | undefined>((acc, urlPattern) => {
+    // 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 (urlPattern.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 = urlPattern.pattern.test(url);
+        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 = urlPattern.pattern.test(url);
+        return matched ? false : acc;
+      }
+    }
+  }, undefined);
+};

packages/client/src/clients/guide/types.ts

@@ -25,7 +25,14 @@ export interface GuideStepData<TContent = Any> {
   content: TContent;
 }
 
-interface GuideActivationLocationRuleData {
+export interface GuideActivationUrlRuleData {
+  directive: "allow" | "block";
+  variable: "pathname";
+  operator: "equal_to" | "contains";
+  argument: string;
+}
+
+interface GuideActivationUrlPatternData {
   directive: "allow" | "block";
   pathname: string;
 }
@@ -38,7 +45,8 @@ export interface GuideData<TContent = Any> {
   type: string;
   semver: string;
   steps: GuideStepData<TContent>[];
-  activation_location_rules: GuideActivationLocationRuleData[];
+  activation_url_rules: GuideActivationUrlRuleData[];
+  activation_url_patterns: GuideActivationUrlPatternData[];
   bypass_global_group_limit: boolean;
   inserted_at: string;
   updated_at: string;
@@ -157,14 +165,14 @@ export interface KnockGuideStep<TContent = Any>
   markAsArchived: () => void;
 }
 
-interface KnockGuideActivationLocationRule
-  extends GuideActivationLocationRuleData {
+export interface KnockGuideActivationUrlPattern
+  extends GuideActivationUrlPatternData {
   pattern: URLPattern;
 }
 
 export interface KnockGuide<TContent = Any> extends GuideData<TContent> {
   steps: KnockGuideStep<TContent>[];
-  activation_location_rules: KnockGuideActivationLocationRule[];
+  activation_url_patterns: KnockGuideActivationUrlPattern[];
   getStep: () => KnockGuideStep<TContent> | undefined;
 }