@windstream/react-shared-components 0.2.83 → 0.2.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windstream/react-shared-components",
-  "version": "0.2.83",
+  "version": "0.2.84",
   "type": "module",
   "description": "Shared React components for Kinetic applications",
   "main": "dist/index.js",

package/src/utils/index.test.ts

@@ -17,6 +17,7 @@ import {
   removeUTMs,
   renderContentfulRichText,
   renderContentfulRichTextTable,
+  replaceTokens,
   setCookie,
   setUTMs,
   SpeedCardBg,
@@ -92,6 +93,10 @@ describe("utils barrel exports", () => {
     expect(typeof toDocument).toBe("function");
   });
 
+  it("exports replaceTokens", () => {
+    expect(typeof replaceTokens).toBe("function");
+  });
+
   it("exports renderContentfulRichText", () => {
     expect(typeof renderContentfulRichText).toBe("function");
   });

package/src/utils/index.ts

@@ -32,6 +32,16 @@ export {
   redirectToWifiGrantUrl,
 } from "./wifi-grant-redirect";
 
+// Token replacement — framework-agnostic string / rich-text interpolation.
+// No dependency on Contentful or any particular CMS/tool.
+export { replaceTokens } from "./replace-tokens";
+export type {
+  TokenEntry,
+  TokenSource,
+  RichTextDocument,
+  ReplaceTokensResult,
+} from "./replace-tokens";
+
 // Contentful utilities (server-safe, no "use client")
 export { toDocument } from "./contentful/to-document";
 export {

package/src/utils/replace-tokens.test.ts

@@ -0,0 +1,197 @@
+import {
+  replaceTokens,
+  type RichTextDocument,
+  type TokenEntry,
+  type TokenSource,
+} from "./replace-tokens";
+
+// Generic rich-text node types. This utility is framework-agnostic and
+// intentionally has no dependency on any CMS or tool.
+const DOCUMENT = "document";
+const PARAGRAPH = "paragraph";
+const HR = "hr";
+
+const tokens: TokenEntry[] = [
+  { token: "price_tier1_300mbps", value: "44.99", promo: "39.99" },
+  { token: "price_value_only", value: "50.00" },
+  { token: "reward_50", value: "50" },
+];
+
+const makeDocument = (value: string): RichTextDocument => ({
+  nodeType: DOCUMENT,
+  content: [
+    {
+      nodeType: PARAGRAPH,
+      content: [{ nodeType: "text", value, marks: [], data: {} }],
+    },
+  ],
+});
+
+describe("replaceTokens - strings", () => {
+  it("resolves a price placeholder to its promo value", () => {
+    expect(replaceTokens("Only ${price_tier1_300mbps}/mo", tokens)).toBe(
+      "Only 39.99/mo"
+    );
+  });
+
+  it("falls back to value when the entry has no promo (reward tokens)", () => {
+    expect(replaceTokens("Get a $${reward_50} reward", tokens)).toBe(
+      "Get a $50 reward"
+    );
+    expect(replaceTokens("${price_value_only}", tokens)).toBe("50.00");
+  });
+
+  it("replaces multiple placeholders in one string", () => {
+    expect(
+      replaceTokens("${price_tier1_300mbps} then ${reward_50}", tokens)
+    ).toBe("39.99 then 50");
+  });
+
+  it("leaves unknown placeholders intact", () => {
+    expect(replaceTokens("was ${not_a_token} now", tokens)).toBe(
+      "was ${not_a_token} now"
+    );
+  });
+
+  it("returns the string unchanged when there are no placeholders", () => {
+    expect(replaceTokens("plain text", tokens)).toBe("plain text");
+  });
+
+  it("accepts a JSON string source", () => {
+    expect(
+      replaceTokens("${price_tier1_300mbps}", JSON.stringify(tokens))
+    ).toBe("39.99");
+  });
+});
+
+describe("replaceTokens - empty / invalid sources", () => {
+  it.each<[string, TokenSource]>([
+    ["undefined", undefined],
+    ["null", null],
+    ["empty array", []],
+    ["blank string", "   "],
+    ["malformed JSON", "not json"],
+    ["non-array JSON", JSON.stringify({ token: "x" })],
+  ])("returns input unchanged for %s source", (_label, source) => {
+    expect(replaceTokens("${price_tier1_300mbps}", source)).toBe(
+      "${price_tier1_300mbps}"
+    );
+  });
+
+  it("ignores entries without a usable token key or value", () => {
+    const source: TokenEntry[] = [
+      { value: "1" },
+      { token: "", value: "2" },
+      { token: "no_values" },
+    ];
+    expect(replaceTokens("${no_values}", source)).toBe("${no_values}");
+  });
+});
+
+describe("replaceTokens - malformed values and ReDoS safety", () => {
+  it("ignores entries whose resolved value is not a string (never throws)", () => {
+    const malformed = [
+      { token: "reward_50", value: { toString: null } },
+      { token: "price_x", promo: 123 },
+    ] as unknown as TokenEntry[];
+
+    expect(replaceTokens("${reward_50} / ${price_x}", malformed)).toBe(
+      "${reward_50} / ${price_x}"
+    );
+  });
+
+  it("falls back to value when promo is not a string", () => {
+    const entries = [
+      { token: "reward_50", promo: { bad: true }, value: "50" },
+    ] as unknown as TokenEntry[];
+
+    expect(replaceTokens("$${reward_50}", entries)).toBe("$50");
+  });
+
+  it("resolves pathological ${-heavy input quickly without backtracking", () => {
+    const evil = "${".repeat(50000);
+    const start = Date.now();
+    const result = replaceTokens(evil, tokens);
+
+    expect(result).toBe(evil);
+    expect(Date.now() - start).toBeLessThan(2000);
+  });
+
+  it("widens a replaced string result to string, not the literal input type", () => {
+    const result = replaceTokens("${reward_50}", tokens);
+    // Compiles only because `result` is `string`; a preserved literal type
+    // would make this comparison a TypeScript no-overlap error.
+    expect(result === "50").toBe(true);
+  });
+});
+
+describe("replaceTokens - empty / non-tokenizable input", () => {
+  it.each([
+    ["empty string", ""],
+    ["null", null],
+    ["undefined", undefined],
+  ])("returns %s input unchanged", (_label, input) => {
+    expect(replaceTokens(input as any, tokens)).toBe(input);
+  });
+
+  it("returns a non-document object unchanged", () => {
+    const obj = { foo: "bar" } as any;
+    expect(replaceTokens(obj, tokens)).toBe(obj);
+  });
+});
+
+describe("replaceTokens - rich text", () => {
+  it("replaces placeholders inside nested text nodes", () => {
+    const doc = makeDocument("Only ${price_tier1_300mbps}/mo");
+    const result = replaceTokens(doc, tokens) as RichTextDocument;
+
+    expect((result.content[0] as any).content[0].value).toBe("Only 39.99/mo");
+  });
+
+  it("does not mutate the original document", () => {
+    const doc = makeDocument("${price_tier1_300mbps}");
+    replaceTokens(doc, tokens);
+
+    expect((doc.content[0] as any).content[0].value).toBe(
+      "${price_tier1_300mbps}"
+    );
+  });
+
+  it("preserves marks and data on text nodes", () => {
+    const doc = makeDocument("${reward_50}");
+    (doc.content[0] as any).content[0].marks = [{ type: "bold" }];
+    const result = replaceTokens(doc, tokens) as RichTextDocument;
+
+    const textNode = (result.content[0] as any).content[0];
+    expect(textNode.value).toBe("50");
+    expect(textNode.marks).toEqual([{ type: "bold" }]);
+  });
+
+  it("returns the document unchanged when no tokens match", () => {
+    const doc = makeDocument("nothing to replace");
+    const result = replaceTokens(doc, tokens) as RichTextDocument;
+
+    expect((result.content[0] as any).content[0].value).toBe(
+      "nothing to replace"
+    );
+  });
+
+  it("leaves non-text leaf nodes (e.g. hr) untouched", () => {
+    const doc: RichTextDocument = {
+      nodeType: DOCUMENT,
+      content: [
+        { nodeType: HR, content: [] },
+        {
+          nodeType: PARAGRAPH,
+          content: [
+            { nodeType: "text", value: "${reward_50}", marks: [], data: {} },
+          ],
+        },
+      ],
+    };
+    const result = replaceTokens(doc, tokens) as RichTextDocument;
+
+    expect((result.content[0] as any).nodeType).toBe(HR);
+    expect((result.content[1] as any).content[0].value).toBe("50");
+  });
+});

package/src/utils/replace-tokens.ts

@@ -0,0 +1,89 @@
+export type TokenEntry = {
+  token?: string;
+  value?: string;
+  promo?: string;
+  [key: string]: unknown;
+};
+
+export type TokenSource = TokenEntry[] | string | null | undefined;
+
+export type RichTextDocument = {
+  nodeType: string;
+  content: unknown[];
+};
+
+export type ReplaceTokensResult<T> = T extends string ? string : T;
+
+const TOKEN_PATTERN = /\$\{([^${}]+)\}/g;
+
+const normalizeEntries = (tokens: TokenSource): TokenEntry[] => {
+  if (Array.isArray(tokens)) return tokens;
+  if (typeof tokens === "string" && tokens.trim()) {
+    try {
+      const parsed = JSON.parse(tokens);
+      return Array.isArray(parsed) ? (parsed as TokenEntry[]) : [];
+    } catch {
+      return [];
+    }
+  }
+  return [];
+};
+
+const buildTokenMap = (tokens: TokenSource): Record<string, string> =>
+  normalizeEntries(tokens).reduce<Record<string, string>>((acc, entry) => {
+    if (entry && typeof entry.token === "string" && entry.token) {
+      const promo = typeof entry.promo === "string" ? entry.promo : undefined;
+      const value = typeof entry.value === "string" ? entry.value : undefined;
+      const resolved = promo ?? value;
+      if (resolved !== undefined) acc[entry.token] = resolved;
+    }
+    return acc;
+  }, {});
+
+const replaceInString = (input: string, map: Record<string, string>): string =>
+  input.replace(TOKEN_PATTERN, (match, token) =>
+    Object.prototype.hasOwnProperty.call(map, token) ? map[token] : match
+  );
+
+const isRichTextDocument = (value: unknown): value is RichTextDocument =>
+  !!value &&
+  typeof value === "object" &&
+  "nodeType" in (value as Record<string, unknown>) &&
+  "content" in (value as Record<string, unknown>);
+
+const replaceInNode = <T>(node: T, map: Record<string, string>): T => {
+  if (!node || typeof node !== "object") return node;
+  const current = node as Record<string, unknown>;
+
+  if (current.nodeType === "text" && typeof current.value === "string") {
+    return { ...current, value: replaceInString(current.value, map) } as T;
+  }
+
+  if (Array.isArray(current.content)) {
+    return {
+      ...current,
+      content: current.content.map(child => replaceInNode(child, map)),
+    } as T;
+  }
+
+  return node;
+};
+
+export function replaceTokens<
+  T extends string | RichTextDocument | null | undefined,
+>(input: T, tokens: TokenSource): ReplaceTokensResult<T> {
+  if (input == null || input === "") return input as ReplaceTokensResult<T>;
+
+  const map = buildTokenMap(tokens);
+  if (Object.keys(map).length === 0) return input as ReplaceTokensResult<T>;
+
+  if (typeof input === "string") {
+    return replaceInString(input, map) as ReplaceTokensResult<T>;
+  }
+
+  if (isRichTextDocument(input)) {
+    return replaceInNode(input, map) as ReplaceTokensResult<T>;
+  }
+
+  return input as ReplaceTokensResult<T>;
+}