@qoretechnologies/reqraft 0.10.56 → 0.10.57-pr.127.g0a792ea

package/src/tracking/ui/client.ts

@@ -0,0 +1,117 @@
+/**
+ * A small client for the qorus-api experiment routes the A/B test card acts on: the list with
+ * results, accept, remove-variant, start, pause, stop, and creating a draft (§9.3, §9.5 of the
+ * contract). Optional: the card and the overlay only take data and callbacks, so a product can
+ * reach its server any other way.
+ */
+import type {
+  IAdminExperiment,
+  IExperimentEntry,
+  INewExperiment,
+  TExperimentActionResult,
+  TLifecycleAction,
+} from './types';
+
+export class ExperimentsAdminError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code?: string
+  ) {
+    super(message);
+    this.name = 'ExperimentsAdminError';
+  }
+}
+
+export type TExperimentsFetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface IExperimentsAdminOptions {
+  /**
+   * The list route, with any query it needs: `/qorus-cloud/editor/experiments?property=landing`
+   * (the editor route) or `/qorus-saas-admin/analytics/experiments?property=ide` (the admin API).
+   */
+  listUrl: string;
+  /**
+   * The route of one action. Default: the list route's path, then `/<key>/<action>`
+   * (`…/experiments/signup-cta/accept`), without the list's query.
+   */
+  actionUrl?: (key: string, action: string) => string;
+  /** Where a new draft is posted. Default: the list route's path. */
+  createUrl?: string;
+  /** Sent with every request (e.g. an `Authorization` header). */
+  headers?: Record<string, string>;
+  /** `same-origin` by default. */
+  credentials?: RequestCredentials;
+  /** Default: the global `fetch`. */
+  fetch?: TExperimentsFetch;
+}
+
+export interface IExperimentsAdminClient {
+  list(): Promise<IExperimentEntry[]>;
+  accept(key: string, variant: string): Promise<TExperimentActionResult>;
+  remove(key: string, variant: string): Promise<TExperimentActionResult>;
+  lifecycle(key: string, action: TLifecycleAction): Promise<IAdminExperiment>;
+  create(def: INewExperiment): Promise<IAdminExperiment>;
+}
+
+const pathOf = (url: string) => url.split('?')[0].replace(/\/+$/, '');
+
+export const createExperimentsAdminClient = (
+  options: IExperimentsAdminOptions
+): IExperimentsAdminClient => {
+  const base = pathOf(options.listUrl);
+  const actionUrl =
+    options.actionUrl ??
+    ((key: string, action: string) => `${base}/${encodeURIComponent(key)}/${action}`);
+  const doFetch: TExperimentsFetch = options.fetch ?? ((input, init) => fetch(input, init));
+
+  const call = async <T>(url: string, body?: unknown): Promise<T> => {
+    const res = await doFetch(url, {
+      method: body === undefined ? 'GET' : 'POST',
+      credentials: options.credentials ?? 'same-origin',
+      headers: {
+        Accept: 'application/json',
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        ...options.headers,
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const parsed = (await res.json().catch(() => null)) as {
+      err?: string;
+      error?: string;
+      desc?: string;
+      message?: string;
+    } | null;
+    if (!res.ok) {
+      const code = parsed?.err ?? parsed?.error;
+      if (res.status === 401 || res.status === 403) {
+        throw new ExperimentsAdminError(
+          'Not allowed to manage A/B tests on this server (the API key is missing or wrong).',
+          res.status,
+          code
+        );
+      }
+      throw new ExperimentsAdminError(
+        parsed?.desc ?? parsed?.message ?? code ?? `HTTP ${res.status}`,
+        res.status,
+        code
+      );
+    }
+    return parsed as T;
+  };
+
+  return {
+    list: () =>
+      call<IExperimentEntry[] | { experiments?: IExperimentEntry[] }>(options.listUrl).then(
+        (body) =>
+          Array.isArray(body) ? body
+          : Array.isArray(body?.experiments) ? body.experiments
+          : []
+      ),
+    accept: (key, variant) => call<TExperimentActionResult>(actionUrl(key, 'accept'), { variant }),
+    remove: (key, variant) =>
+      call<TExperimentActionResult>(actionUrl(key, 'remove-variant'), { variant }),
+    lifecycle: (key, action) => call<IAdminExperiment>(actionUrl(key, action), {}),
+    create: (def) => call<IAdminExperiment>(options.createUrl ?? base, def),
+  };
+};

package/src/tracking/ui/index.ts

@@ -0,0 +1,77 @@
+/**
+ * The A/B test UI: `<ExperimentCard>` (one test, driven by props), `<ExperimentsOverlay>` (every
+ * `<Experiment>` on the page outlined, with its card anchored to it), and the optional
+ * `useExperimentsAdmin` / `createExperimentsAdminClient` for the qorus-api routes. Built on Reqore;
+ * the engine (`../index`) does not import this layer. How to embed it: design/TRACKING.md, §8.
+ */
+export { ExperimentCard } from './ExperimentCard';
+export type { IExperimentCardProps } from './ExperimentCard';
+export { boxOf, ExperimentsOverlay, OVERLAY_ATTRIBUTE } from './ExperimentsOverlay';
+export type { IExperimentsOverlayProps } from './ExperimentsOverlay';
+export { useExperimentsAdmin } from './useExperimentsAdmin';
+export type { IUseExperimentsAdmin, IUseExperimentsAdminOptions } from './useExperimentsAdmin';
+export { createExperimentsAdminClient, ExperimentsAdminError } from './client';
+export type {
+  IExperimentsAdminClient,
+  IExperimentsAdminOptions,
+  TExperimentsFetch,
+} from './client';
+export {
+  activatesRow,
+  CARD_MAX_WIDTH,
+  CARD_MIN_HEIGHT,
+  cardReducer,
+  CLOSED,
+  openCard,
+  OUTSIDE_IGNORE,
+  placeCard,
+} from './anchor';
+export type { IBox, ICardState, IPlaceInput, IPlacement, TCardEvent } from './anchor';
+export {
+  actionOutcome,
+  barValues,
+  canAccept,
+  canPause,
+  canRemove,
+  canStart,
+  canStop,
+  confirmCopy,
+  count,
+  DEFAULT_MIN_SAMPLE,
+  helpSections,
+  leadingVersion,
+  NOT_SET_UP_TEXT,
+  sortVersionRows,
+  UNREACHABLE_TEXT,
+  lifecycleCopy,
+  numbersLine,
+  percent,
+  phaseNote,
+  primaryMetric,
+  STATUS_LABEL,
+  statusTag,
+  verdictIntent,
+  verdictLine,
+  versionName,
+  versionRows,
+  versionsMaxHeight,
+  VISIBLE_VERSIONS,
+  winnerNote,
+} from './card';
+export type { IConfirmCopy, IHelpSection, IVersionRow, TStatusIntent } from './card';
+export type {
+  IAdminExperiment,
+  IAdminExperimentEvent,
+  IAdminExperimentPhase,
+  IAdminVariant,
+  IExperimentEntry,
+  IExperimentResults,
+  INewExperiment,
+  IResultsMetric,
+  IResultsVariant,
+  TExperimentAction,
+  TExperimentActionResult,
+  TExperimentStatus,
+  TLifecycleAction,
+  TVersionAction,
+} from './types';

package/src/tracking/ui/types.ts

@@ -0,0 +1,110 @@
+/**
+ * The experiment and results objects of the qorus-api admin and editor routes (§5, §7, §9.5 of
+ * `design/analytics-and-experiments-design.md`), with the fields the A/B test UI reads.
+ * Change the contract there first, then here.
+ */
+
+export type TExperimentStatus =
+  'draft' | 'running' | 'paused' | 'stopped' | 'concluded' | 'archived';
+
+export interface IAdminVariant {
+  key: string;
+  name?: string;
+  weight: number;
+  control?: boolean;
+}
+
+export interface IAdminExperimentPhase {
+  phase: number;
+  started_at: string;
+  ended_at: string | null;
+  variants: IAdminVariant[];
+}
+
+export interface IAdminExperimentEvent {
+  at: string;
+  action: string;
+  variant?: string | null;
+  /** Who did it (`admin`, or the product's editor, e.g. `landing-editor`). */
+  actor: string;
+  user?: string;
+}
+
+/** The admin experiment object. */
+export interface IAdminExperiment {
+  key: string;
+  name?: string;
+  property?: string;
+  status: TExperimentStatus;
+  variants: IAdminVariant[];
+  winner?: string | null;
+  /** The current phase: a removed version starts a new one, and the numbers count from zero. */
+  phase?: number;
+  /** Earlier phases and the current one (last, `ended_at: null` while it runs). */
+  phases?: IAdminExperimentPhase[];
+  /** Every state change, oldest first. */
+  history?: IAdminExperimentEvent[];
+  metrics?: { primary?: string; guardrails?: string[]; secondary?: string[] };
+  /** Share of visitors in the test, 0..1. */
+  traffic?: number;
+  /** The too-early gate: every version needs `per_variant` visitors and `days` must pass (default 200, 7). */
+  min_sample?: { per_variant: number; days: number };
+  started_at?: string | null;
+  ended_at?: string | null;
+}
+
+export interface IResultsVariant {
+  variant: string;
+  exposed: number;
+  converters: number;
+  rate: number | null;
+  uplift?: number | null;
+  chance_to_beat: number | null;
+}
+
+export interface IResultsMetric {
+  key: string;
+  name?: string;
+  role: 'primary' | 'guardrail' | 'secondary';
+  verdict?: string;
+  verdict_text?: string;
+  variants: IResultsVariant[];
+  unavailable?: string;
+}
+
+/** The admin results object. */
+export interface IExperimentResults {
+  verdict?: string;
+  /** The verdict in plain words, written by the server. */
+  verdict_text?: string;
+  winner_variant?: string | null;
+  phase?: number;
+  metrics: IResultsMetric[];
+}
+
+/** One entry of the editor list: the experiment and its results (null for a draft). */
+export interface IExperimentEntry {
+  experiment: IAdminExperiment;
+  results: IExperimentResults | null;
+}
+
+/** The experiment an action returns; `auto_accepted` when removing left one version. */
+export type TExperimentActionResult = IAdminExperiment & { auto_accepted?: boolean };
+
+export type TLifecycleAction = 'start' | 'pause' | 'stop';
+export type TVersionAction = 'accept' | 'remove';
+export type TExperimentAction = TVersionAction | TLifecycleAction;
+
+/** A new experiment definition (admin shape); the server always creates it as a draft. */
+export interface INewExperiment {
+  key: string;
+  name: string;
+  hypothesis?: string;
+  property?: string;
+  variants: IAdminVariant[];
+  traffic?: number;
+  targeting?: { paths?: string[] | null; device?: string | null; lang?: string | null };
+  trigger?: { section?: string | null };
+  metrics: { primary: string; guardrails?: string[]; secondary?: string[] };
+  min_sample?: { per_variant: number; days: number };
+}

package/src/tracking/ui/useExperimentsAdmin.ts

@@ -0,0 +1,103 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  createExperimentsAdminClient,
+  type IExperimentsAdminClient,
+  type IExperimentsAdminOptions,
+} from './client';
+import type { IExperimentEntry, TExperimentActionResult, TLifecycleAction } from './types';
+
+export interface IUseExperimentsAdminOptions extends IExperimentsAdminOptions {
+  /** Reload the list this often (someone else may accept a test meanwhile). Default 60 s; 0 turns it off. */
+  refreshMs?: number;
+  /** Load nothing while false (e.g. while the overlay is hidden). Default true. */
+  enabled?: boolean;
+}
+
+export interface IUseExperimentsAdmin {
+  /** The list, or null before the first answer. */
+  tests: IExperimentEntry[] | null;
+  /** The last load's error message, or null. */
+  error: string | null;
+  reload: () => Promise<void>;
+  /** Each action reloads the list when it resolves, and rejects with the server's words. */
+  accept: (key: string, variant: string) => Promise<TExperimentActionResult>;
+  remove: (key: string, variant: string) => Promise<TExperimentActionResult>;
+  start: (key: string) => Promise<unknown>;
+  pause: (key: string) => Promise<unknown>;
+  stop: (key: string) => Promise<unknown>;
+  client: IExperimentsAdminClient;
+}
+
+/**
+ * The A/B test list and its actions from the qorus-api routes, for `<ExperimentsOverlay>` or
+ * `<ExperimentCard>`. Optional and replaceable: both components take plain data and callbacks.
+ *
+ *   const admin = useExperimentsAdmin({ listUrl: '/qorus-cloud/editor/experiments?property=landing' });
+ *   <ExperimentsOverlay tests={admin.tests} loadError={admin.error} onAccept={admin.accept} … />
+ */
+export const useExperimentsAdmin = (options: IUseExperimentsAdminOptions): IUseExperimentsAdmin => {
+  const { refreshMs = 60_000, enabled = true } = options;
+  // The options object is usually a fresh literal: the client follows its values, not its identity.
+  const latest = useRef(options);
+  latest.current = options;
+  const headersKey = JSON.stringify(options.headers ?? {});
+  const client = useMemo(
+    () =>
+      createExperimentsAdminClient({
+        ...latest.current,
+        fetch: (input, init) => (latest.current.fetch ?? fetch)(input, init),
+      }),
+    [options.listUrl, options.createUrl, options.credentials, headersKey]
+  );
+  const [tests, setTests] = useState<IExperimentEntry[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const alive = useRef(true);
+
+  const reload = useCallback(async () => {
+    try {
+      const list = await client.list();
+      if (!alive.current) return;
+      setTests(list);
+      setError(null);
+    } catch (err) {
+      if (alive.current) setError((err as Error).message);
+    }
+  }, [client]);
+
+  useEffect(() => {
+    alive.current = true;
+    if (!enabled) return () => undefined;
+    void reload();
+    const id = refreshMs > 0 ? setInterval(() => void reload(), refreshMs) : null;
+    return () => {
+      alive.current = false;
+      if (id) clearInterval(id);
+    };
+  }, [reload, enabled, refreshMs]);
+
+  const then = useCallback(
+    async <T>(promise: Promise<T>): Promise<T> => {
+      const result = await promise;
+      await reload();
+      return result;
+    },
+    [reload]
+  );
+
+  const lifecycle = useCallback(
+    (key: string, action: TLifecycleAction) => then(client.lifecycle(key, action)),
+    [client, then]
+  );
+
+  return {
+    tests,
+    error,
+    reload,
+    accept: useCallback((key, variant) => then(client.accept(key, variant)), [client, then]),
+    remove: useCallback((key, variant) => then(client.remove(key, variant)), [client, then]),
+    start: useCallback((key) => lifecycle(key, 'start'), [lifecycle]),
+    pause: useCallback((key) => lifecycle(key, 'pause'), [lifecycle]),
+    stop: useCallback((key) => lifecycle(key, 'stop'), [lifecycle]),
+    client,
+  };
+};