@qoretechnologies/reqraft 0.10.66-pr.145.gcb1e59d → 0.10.66

package/src/tracking/ui/client.ts

@@ -1,117 +0,0 @@
-/**
- * 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

@@ -1,77 +0,0 @@
-/**
- * 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

@@ -1,110 +0,0 @@
-/**
- * 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

@@ -1,103 +0,0 @@
-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/types/Form.ts

@@ -1,29 +0,0 @@
-import { TQorusType } from '@qoretechnologies/ts-toolkit';
-import { IColorFormFieldProps } from '../components/form/fields/color/Color';
-
-// The server's TQorusType plus the toolkit-only dispatcher types: `soft*`
-// variants (rendered as their concrete base) and the composite fields the
-// IDE routes via `ui_type`.
-export type TFormFieldType =
-  | TQorusType
-  | 'softint' | 'softstring' | 'softbool' | 'softfloat' | 'softnumber' | 'softdate' | 'softlist'
-  | 'byte-size'
-  // the server emits this for a connection's connect_timeout / timeout;
-  // it is not (yet) in ts-toolkit's TQorusType
-  | 'timeout'
-  | 'multi-select'
-  | 'schema-definition';
-
-export type TFormFieldValueType<T> =
-  T extends 'string' | 'long-string' | 'binary' | 'email' | 'url' | 'enum' | 'select-string' | 'file-as-string' | 'byte-size' ? string
-  : T extends 'int' | 'integer' | 'float' | 'number' | 'timeout' ? number
-  : T extends 'bool' | 'boolean' ? boolean
-  : T extends 'date' ? Date | string
-  : T extends 'hash' | 'free-hash' | 'data' ? Record<string, any>
-  : T extends 'list' | 'free-list' | 'range' | 'multi-select' ? unknown[]
-  : T extends 'rgbcolor' ? IColorFormFieldProps['value']
-  : T extends 'file' ? File
-  : T extends 'richtext' ? string
-  : T extends 'auto' | 'any' ? any
-  : T extends 'null' | 'nothing' ? null
-  : any;

package/src/types.ts

@@ -1,14 +0,0 @@
-import { IReqoreUIProviderProps } from '@qoretechnologies/reqore/dist/containers/UIProvider';
-import { Meta } from '@storybook/react-vite';
-import { IReqraftProviderProps } from './providers/ReqraftProvider';
-
-export type StoryMeta<
-  Component extends keyof JSX.IntrinsicElements | React.JSXElementConstructor<any>,
-  AdditionalArgs = Record<string, any>,
-> = Meta<
-  React.ComponentProps<Component> &
-    AdditionalArgs & {
-      reqoreOptions: IReqoreUIProviderProps['options'];
-      reqraftOptions: IReqraftProviderProps;
-    }
->;

package/src/utils/datetime.ts

@@ -1,10 +0,0 @@
-export const getCurrentTimeWithMilliseconds = () => {
-  const now = new Date();
-  const hours = String(now.getHours()).padStart(2, '0');
-  const minutes = String(now.getMinutes()).padStart(2, '0');
-  const seconds = String(now.getSeconds()).padStart(2, '0');
-  const milliseconds = String(now.getMilliseconds()).padStart(3, '0');
-  const timestamp = `${hours}:${minutes}:${seconds}:${milliseconds}`;
-
-  return timestamp;
-};