@qoretechnologies/reqraft 0.10.57-pr.127.ge03fd3a → 0.10.57

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,
+  };
+};

package/src/tracking/react/Experiment.stories.tsx

@@ -1,174 +0,0 @@
-import { ReqoreControlGroup, ReqoreP, ReqorePanel, ReqoreTag, ReqoreTagGroup } from '@qoretechnologies/reqore';
-import { StoryObj } from '@storybook/react-vite';
-import { useState } from 'react';
-import { expect, within } from 'storybook/test';
-import { StoryMeta } from '../../types';
-import { KEYS, type IExperimentDefinition } from '../core/types';
-import { createMemoryTracker, type IMemoryTrackerOptions } from '../testing';
-import { Experiment } from './Experiment';
-import { useExperiment } from './hooks';
-import { TrackingProvider } from './TrackingProvider';
-
-const KEY = 'signup-cta';
-
-const RUNNING: IExperimentDefinition = {
-  key: KEY,
-  status: 'running',
-  variants: [
-    { key: 'a', weight: 0.5, control: true },
-    { key: 'b', weight: 0.5 },
-  ],
-  traffic: 1,
-  trigger: null,
-};
-
-/** `createMemoryTracker`'s clock starts here; the cached definitions are fresh for it. */
-const CLOCK = Date.UTC(2026, 8, 29, 10, 0, 0);
-
-/**
- * The definitions as the tracker caches them after a fetch, so the first render already
- * has them (a real app gets the same from its cache on every visit after the first).
- */
-const cached = (experiments: IExperimentDefinition[]) => ({
-  [KEYS.experimentsCache]: JSON.stringify({ at: CLOCK, property: 'test', experiments }),
-});
-
-/** A visitor id whose GrowthBook hash for `signup-cta` lands in version B at 50/50. */
-const VISITOR_IN_B = 'visitor-3';
-
-const Version = ({ letter, label }: { letter: string; label: string }) => (
-  <ReqorePanel label={`Version ${letter}`} flat>
-    <ReqoreP>{label}</ReqoreP>
-  </ReqorePanel>
-);
-
-const VARIANTS = {
-  a: <Version letter='A' label='The control: what every visitor sees without the experiment.' />,
-  b: <Version letter='B' label='The challenger: shown only to visitors assigned to it.' />,
-};
-
-/** Shows why this visitor sees what they see (the same assignment `<Experiment>` uses). */
-const Reason = () => {
-  const { variant, assignment } = useExperiment(KEY, { variants: ['a', 'b'] });
-  return (
-    <ReqoreTagGroup>
-      <ReqoreTag labelKey='Shown' label={variant.toUpperCase()} />
-      <ReqoreTag labelKey='Reason' label={assignment.reason} />
-      <ReqoreTag labelKey='Counts for the test' label={assignment.enrolled ? 'yes' : 'no'} />
-    </ReqoreTagGroup>
-  );
-};
-
-const Demo = ({ tracking }: { tracking?: IMemoryTrackerOptions }) => {
-  const [memory] = useState(() => (tracking ? createMemoryTracker(tracking) : null));
-  return (
-    <TrackingProvider tracker={memory?.tracker ?? null} location='/'>
-      <ReqoreControlGroup vertical fluid>
-        <Reason />
-        <Experiment id={KEY} variants={VARIANTS} />
-      </ReqoreControlGroup>
-    </TrackingProvider>
-  );
-};
-
-const meta = {
-  title: 'Tracking/Experiment',
-  component: Demo,
-} as StoryMeta<typeof Demo>;
-
-export default meta;
-export type Story = StoryObj<typeof meta>;
-
-const expectShown = async (canvasElement: HTMLElement, variant: string, reason: string) => {
-  const canvas = within(canvasElement);
-  await expect(await canvas.findByText(`Version ${variant.toUpperCase()}`)).toBeInTheDocument();
-  const wrapper = canvasElement.querySelector(`[data-experiment="${KEY}"]`) as HTMLElement;
-  await expect(wrapper.dataset.variant).toBe(variant);
-  await expect(wrapper.dataset.experimentReason).toBe(reason);
-  await expect(canvas.getByText(reason)).toBeInTheDocument();
-};
-
-export const ControlWithoutTracker: Story = {
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Renders an experiment with no tracker behind it (as before the visitor answered the consent prompt). Shows version A, the control, with the reason `no-consent`.',
-      },
-    },
-  },
-  play: async ({ canvasElement }) => {
-    await expectShown(canvasElement, 'a', 'no-consent');
-  },
-};
-
-export const AssignedVariant: Story = {
-  args: {
-    tracking: { consent: 'granted', vid: VISITOR_IN_B, seed: cached([RUNNING]) },
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Renders a running 50/50 experiment for a visitor who allowed tracking and whose id hashes into version B. Shows version B, reason `assigned`, counted for the test.',
-      },
-    },
-  },
-  play: async ({ canvasElement }) => {
-    await expectShown(canvasElement, 'b', 'assigned');
-    await expect(within(canvasElement).getByText('yes')).toBeInTheDocument();
-  },
-};
-
-export const NotEnrolled: Story = {
-  args: {
-    tracking: { consent: 'granted', vid: VISITOR_IN_B, seed: cached([{ ...RUNNING, traffic: 0 }]) },
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Renders a running experiment with a traffic share of 0 for a visitor who allowed tracking. Shows version A, reason `not-enrolled`, not counted for the test.',
-      },
-    },
-  },
-  play: async ({ canvasElement }) => {
-    await expectShown(canvasElement, 'a', 'not-enrolled');
-  },
-};
-
-export const PreviewLink: Story = {
-  args: {
-    tracking: { page: { search: `?qa_variant=${KEY}:b` }, seed: cached([RUNNING]) },
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Renders the experiment opened through a `?qa_variant=signup-cta:b` preview link, without consent. Shows version B with the reason `preview`, never counted.',
-      },
-    },
-  },
-  play: async ({ canvasElement }) => {
-    await expectShown(canvasElement, 'b', 'preview');
-  },
-};
-
-export const ConcludedWinner: Story = {
-  args: {
-    tracking: {
-      seed: cached([{ key: KEY, status: 'concluded', winner: 'b' } as IExperimentDefinition]),
-    },
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Renders an experiment that ended with version B as the winner, for a visitor who never answered the consent prompt. Shows version B to everybody, reason `concluded`.',
-      },
-    },
-  },
-  play: async ({ canvasElement }) => {
-    await expectShown(canvasElement, 'b', 'concluded');
-  },
-};