@drip-apex/sdk 0.1.0

package/src/signals.ts

@@ -0,0 +1,226 @@
+type SignalValue = string | number | boolean | string[] | Record<string, unknown> | null;
+
+type StoredSignal = {
+  value: SignalValue;
+  updatedAt: number;
+  expiresAt?: number;
+};
+
+export type ProductSignalInput = {
+  id?: string | number | null;
+  handle?: string | null;
+  title?: string | null;
+  type?: string | null;
+  vendor?: string | null;
+  tags?: string[] | null;
+  price?: number | string | null;
+};
+
+const STORE_KEY = "drip_signals_v1";
+const VISITOR_SEEN_KEY = "drip_visitor_seen_v1";
+const DEFAULT_TTL_DAYS = 30;
+const MAX_ARRAY_LENGTH = 24;
+const MAX_VALUE_BYTES = 4096;
+const runtimeSignals: Record<string, SignalValue> = {};
+const signalSources: Record<string, string> = {};
+let signalPersistenceAllowed: () => boolean = () => true;
+
+function now(): number {
+  return Date.now();
+}
+
+function ttlMs(days: number): number {
+  return Math.max(1, days) * 86400 * 1000;
+}
+
+function canUseLocalStorage(): boolean {
+  if (!canPersistSignals()) return false;
+  try {
+    if (typeof localStorage === "undefined") return false;
+    const key = "__drip_signal_test__";
+    localStorage.setItem(key, "1");
+    localStorage.removeItem(key);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function canPersistSignals(): boolean {
+  try {
+    return signalPersistenceAllowed() === true;
+  } catch {
+    return false;
+  }
+}
+
+export function configureSignalPersistenceAllowed(predicate?: () => boolean): void {
+  signalPersistenceAllowed = predicate ?? (() => true);
+}
+
+function readStore(): Record<string, StoredSignal> {
+  if (!canUseLocalStorage()) return {};
+  try {
+    const parsed = JSON.parse(localStorage.getItem(STORE_KEY) || "{}");
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeStore(store: Record<string, StoredSignal>): void {
+  if (!canUseLocalStorage()) return;
+  try {
+    localStorage.setItem(STORE_KEY, JSON.stringify(store));
+  } catch {}
+}
+
+function normalizeValue(value: unknown): SignalValue | undefined {
+  if (value === null) return null;
+  if (typeof value === "string") return value.slice(0, 1000);
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (typeof value === "boolean") return value;
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => String(item).trim())
+      .filter(Boolean)
+      .slice(0, MAX_ARRAY_LENGTH);
+  }
+  if (value && typeof value === "object") {
+    try {
+      const json = JSON.stringify(value);
+      if (json.length > MAX_VALUE_BYTES) return undefined;
+      return JSON.parse(json);
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+function compactStore(store: Record<string, StoredSignal>): Record<string, StoredSignal> {
+  const ts = now();
+  const next: Record<string, StoredSignal> = {};
+  for (const [key, entry] of Object.entries(store)) {
+    if (!entry || typeof entry !== "object") continue;
+    if (entry.expiresAt && entry.expiresAt <= ts) continue;
+    next[key] = entry;
+  }
+  return next;
+}
+
+export function setSignal(key: string, value: unknown, ttlDays = DEFAULT_TTL_DAYS, source = "manual"): void {
+  if (!canPersistSignals()) return;
+  const normalized = normalizeValue(value);
+  if (normalized === undefined) return;
+  const store = compactStore(readStore());
+  store[key] = {
+    value: normalized,
+    updatedAt: now(),
+    expiresAt: now() + ttlMs(ttlDays),
+  };
+  writeStore(store);
+  signalSources[key] = source;
+}
+
+export function getSignals(options: { markVisitorSeen?: boolean } = {}): Record<string, SignalValue> {
+  const store = compactStore(readStore());
+  if (options.markVisitorSeen !== false) writeStore(store);
+  const signals: Record<string, SignalValue> = {};
+  for (const [key, entry] of Object.entries(store)) {
+    signals[key] = entry.value;
+  }
+  Object.assign(signals, runtimeSignals);
+
+  if (options.markVisitorSeen !== false && canPersistSignals()) {
+    try {
+      const seen = localStorage.getItem(VISITOR_SEEN_KEY) === "1";
+      signals["visitor.returning"] = seen;
+      localStorage.setItem(VISITOR_SEEN_KEY, "1");
+    } catch {}
+  }
+
+  return signals;
+}
+
+export function clearStoredSignals(): void {
+  try {
+    localStorage.removeItem(STORE_KEY);
+    localStorage.removeItem(VISITOR_SEEN_KEY);
+  } catch {}
+}
+
+export function setRuntimeSignal(key: string, value: unknown, source = "runtime"): void {
+  const normalized = normalizeValue(value);
+  if (normalized === undefined) return;
+  runtimeSignals[key] = normalized;
+  signalSources[key] = source;
+}
+
+export function clearRuntimeSignal(key: string): void {
+  delete runtimeSignals[key];
+  delete signalSources[key];
+}
+
+export function getSignalDiagnostics(options: { markVisitorSeen?: boolean } = {}): { values: Record<string, SignalValue>; sources: Record<string, string> } {
+  const values = getSignals(options);
+  return {
+    values,
+    sources: { ...signalSources },
+  };
+}
+
+function prependUnique(values: string[], next: string): string[] {
+  const clean = next.trim();
+  if (!clean) return values;
+  return [clean, ...values.filter((value) => value !== clean)].slice(0, MAX_ARRAY_LENGTH);
+}
+
+function readStringArray(key: string): string[] {
+  const value = getSignals({ markVisitorSeen: false })[key];
+  return Array.isArray(value) ? value.map((item) => String(item)) : [];
+}
+
+export function rememberProduct(product: ProductSignalInput, ttlDays = DEFAULT_TTL_DAYS): void {
+  const id = product.id == null ? "" : String(product.id);
+  const handle = product.handle ? String(product.handle) : "";
+  const productType = product.type ? String(product.type) : "";
+
+  if (id) {
+    setSignal("recently_viewed.product_ids", prependUnique(readStringArray("recently_viewed.product_ids"), id), ttlDays);
+  }
+  if (handle) {
+    setSignal("recently_viewed.product_handles", prependUnique(readStringArray("recently_viewed.product_handles"), handle), ttlDays);
+  }
+  if (productType) {
+    setSignal(
+      "recently_viewed.product_types",
+      prependUnique(readStringArray("recently_viewed.product_types"), productType),
+      ttlDays,
+    );
+  }
+  if (product.tags?.length) {
+    const existing = readStringArray("recently_viewed.product_tags");
+    const next = product.tags.reduce((acc, tag) => prependUnique(acc, String(tag)), existing);
+    setSignal("recently_viewed.product_tags", next, ttlDays);
+  }
+  setSignal("recently_viewed.last_product", {
+    id: id || undefined,
+    handle: handle || undefined,
+    title: product.title || undefined,
+    type: productType || undefined,
+    vendor: product.vendor || undefined,
+    price: product.price ?? undefined,
+  }, ttlDays);
+}
+
+export function setCartSignals(args: { itemCount?: number; productIds?: string[] }, ttlDays = 14): void {
+  if (typeof args.itemCount === "number") setSignal("cart.item_count", args.itemCount, ttlDays);
+  if (args.productIds) setSignal("cart.product_ids", args.productIds, ttlDays);
+}
+
+export function setSearchSignal(query: string, ttlDays = 7): void {
+  const trimmed = query.trim();
+  if (!trimmed) return;
+  setSignal("search.last_query", trimmed, ttlDays);
+}

package/src/surface-signals.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { CART_DRAWER_OPEN_SIGNAL, detectCartDrawerOpen } from "./surface-signals";
+import { clearRuntimeSignal, getSignals, setRuntimeSignal } from "./signals";
+
+class FakeElement {
+  private attrs = new Map<string, string>();
+
+  constructor(attrs: Record<string, string> = {}) {
+    for (const [key, value] of Object.entries(attrs)) {
+      this.attrs.set(key, value);
+    }
+  }
+
+  getAttribute(name: string): string | null {
+    return this.attrs.get(name) ?? null;
+  }
+
+  hasAttribute(name: string): boolean {
+    return this.attrs.has(name);
+  }
+
+  getBoundingClientRect() {
+    return { width: 320, height: 640 };
+  }
+}
+
+function installDom(candidates: FakeElement[], bodyClass = "") {
+  const body = new FakeElement({ class: bodyClass });
+  vi.stubGlobal("window", {
+    getComputedStyle: () => ({
+      display: "block",
+      opacity: "1",
+      pointerEvents: "auto",
+      visibility: "visible",
+    }),
+  });
+  vi.stubGlobal("document", {
+    body,
+    querySelectorAll: () => candidates,
+  });
+  return {
+    querySelectorAll: () => candidates,
+  };
+}
+
+describe("surface signals", () => {
+  beforeEach(() => {
+    vi.stubGlobal("localStorage", {
+      getItem: () => null,
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    });
+  });
+
+  afterEach(() => {
+    clearRuntimeSignal(CART_DRAWER_OPEN_SIGNAL);
+    vi.unstubAllGlobals();
+  });
+
+  it("detects a cart drawer body open state", () => {
+    const root = installDom([], "cart-drawer-open");
+    expect(detectCartDrawerOpen(root as unknown as ParentNode)).toBe(true);
+  });
+
+  it("detects an open visible cart drawer element", () => {
+    const root = installDom([
+      new FakeElement({ class: "cart-drawer is-active", "aria-hidden": "false" }),
+    ]);
+    expect(detectCartDrawerOpen(root as unknown as ParentNode)).toBe(true);
+  });
+
+  it("does not detect closed cart drawer elements", () => {
+    const root = installDom([
+      new FakeElement({ class: "cart-drawer is-hidden", "aria-hidden": "true" }),
+    ]);
+    expect(detectCartDrawerOpen(root as unknown as ParentNode)).toBe(false);
+  });
+
+  it("exposes runtime surface state through targeting signals", () => {
+    setRuntimeSignal(CART_DRAWER_OPEN_SIGNAL, true);
+    expect(getSignals()[CART_DRAWER_OPEN_SIGNAL]).toBe(true);
+  });
+});

package/src/surface-signals.ts

@@ -0,0 +1,165 @@
+import { clearRuntimeSignal, setRuntimeSignal } from "./signals";
+
+export const CART_DRAWER_OPEN_SIGNAL = "surface.cart_drawer.open";
+
+const BODY_OPEN_PATTERN =
+  /\b(cart|mini-cart|side-cart|cart-drawer|drawer)[-_ ]?(open|opened|active|visible|shown)\b|\b(open|active|visible|shown)[-_ ]?(cart|mini-cart|side-cart|cart-drawer|drawer)\b/i;
+
+export const CART_DRAWER_SELECTORS = [
+  "cart-drawer",
+  "mini-cart",
+  "side-cart",
+  "[data-cart-drawer]",
+  "[data-cart-drawer-open]",
+  "[data-side-cart]",
+  "[data-mini-cart]",
+  "[data-state='open'][class*='cart' i]",
+  "[data-state='open'][id*='cart' i]",
+  "[aria-hidden='false'][class*='cart' i][class*='drawer' i]",
+  "[aria-hidden='false'][id*='cart' i][id*='drawer' i]",
+  "[class*='cart-drawer' i]",
+  "[class*='mini-cart' i]",
+  "[class*='side-cart' i]",
+  "[id*='cart-drawer' i]",
+  "[id*='mini-cart' i]",
+  "[id*='side-cart' i]",
+];
+
+export function findCartDrawerContainer(
+  root: ParentNode = document,
+): Element | null {
+  if (typeof document === "undefined") return null;
+  for (const selector of CART_DRAWER_SELECTORS) {
+    const element = root.querySelector(selector);
+    if (element) return element;
+  }
+  return null;
+}
+
+function classNameOf(element: Element): string {
+  const value = element.getAttribute("class");
+  return typeof value === "string" ? value : "";
+}
+
+function hasOpenHint(element: Element): boolean {
+  const classes = classNameOf(element);
+  const state = element.getAttribute("data-state") ?? "";
+  return (
+    element.hasAttribute("open") ||
+    element.getAttribute("aria-hidden") === "false" ||
+    element.getAttribute("aria-expanded") === "true" ||
+    /^(open|opened|active|visible|shown)$/i.test(state) ||
+    /\b(is-|has-)?(open|opened|active|visible|shown)\b/i.test(classes)
+  );
+}
+
+function isExplicitlyClosed(element: Element): boolean {
+  const classes = classNameOf(element);
+  return (
+    element.hasAttribute("hidden") ||
+    element.getAttribute("aria-hidden") === "true" ||
+    element.getAttribute("data-state") === "closed" ||
+    /\b(is-)?(closed|closing|hidden)\b/i.test(classes)
+  );
+}
+
+function isRendered(element: Element): boolean {
+  if (typeof window === "undefined") return false;
+  const node = element as HTMLElement;
+  const style = window.getComputedStyle ? window.getComputedStyle(node) : null;
+  if (
+    style &&
+    (style.display === "none" ||
+      style.visibility === "hidden" ||
+      style.opacity === "0" ||
+      style.pointerEvents === "none")
+  ) {
+    return false;
+  }
+  const rect = node.getBoundingClientRect?.();
+  return Boolean(rect && rect.width > 0 && rect.height > 0);
+}
+
+export function detectCartDrawerOpen(root: ParentNode = document): boolean {
+  if (typeof document === "undefined") return false;
+  const bodyClasses = document.body ? classNameOf(document.body) : "";
+  if (BODY_OPEN_PATTERN.test(bodyClasses)) return true;
+
+  for (const selector of CART_DRAWER_SELECTORS) {
+    const candidates = Array.from(root.querySelectorAll(selector));
+    for (const element of candidates) {
+      if (isExplicitlyClosed(element)) continue;
+      if (!hasOpenHint(element)) continue;
+      if (isRendered(element)) return true;
+    }
+  }
+
+  return false;
+}
+
+export function installCartDrawerOpenListener(
+  onChange: (open: boolean) => void,
+): () => void {
+  if (
+    typeof document === "undefined" ||
+    typeof window === "undefined" ||
+    typeof MutationObserver === "undefined" ||
+    !document.documentElement
+  ) {
+    return () => {};
+  }
+
+  let current = detectCartDrawerOpen();
+
+  let timeoutId: number | null = null;
+  const check = () => {
+    timeoutId = null;
+    const next = detectCartDrawerOpen();
+    if (next === current) return;
+    current = next;
+    onChange(next);
+  };
+  const schedule = () => {
+    if (timeoutId !== null) return;
+    timeoutId = window.setTimeout(check, 80);
+  };
+
+  const observer = new MutationObserver(schedule);
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: [
+      "aria-expanded",
+      "aria-hidden",
+      "class",
+      "data-state",
+      "hidden",
+      "open",
+      "style",
+    ],
+    childList: true,
+    subtree: true,
+  });
+
+  document.addEventListener("click", schedule, true);
+  document.addEventListener("keyup", schedule, true);
+
+  return () => {
+    observer.disconnect();
+    document.removeEventListener("click", schedule, true);
+    document.removeEventListener("keyup", schedule, true);
+    if (timeoutId !== null) window.clearTimeout(timeoutId);
+  };
+}
+
+export function installSurfaceSignals(onChange: () => void): () => void {
+  const current = detectCartDrawerOpen();
+  setRuntimeSignal(CART_DRAWER_OPEN_SIGNAL, current);
+  const stop = installCartDrawerOpenListener((open) => {
+    setRuntimeSignal(CART_DRAWER_OPEN_SIGNAL, open);
+    onChange();
+  });
+  return () => {
+    stop();
+    clearRuntimeSignal(CART_DRAWER_OPEN_SIGNAL);
+  };
+}