@shipeasy/openapi 1.5.0 → 2.1.0

package/dist/resources/experiments.js

@@ -1,707 +0,0 @@
-// src/resources/experiments.ts
-import { z as z4 } from "zod";
-
-// src/schemas/experiments.ts
-import { z as z3 } from "zod";
-
-// src/schemas/folder.ts
-import { z } from "zod";
-var folderSchema = z.string().max(256).regex(/^[a-zA-Z0-9_-]+$/, "Folder must be alphanumeric, `_` or `-` (no `/`).").nullable().optional().describe(
-  "Optional folder name used to group items in the dashboard. Part of the SDK lookup key: an item in folder `checkout` named `new-cart` is referenced as `checkout/new-cart` from the SDK."
-);
-
-// src/schemas/metric-name.ts
-import { z as z2 } from "zod";
-var metricNameSchema = z2.string().regex(/^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$/).max(128);
-
-// src/schemas/experiments.ts
-var experimentInlineMetricSchema = z3.object({
-  name: metricNameSchema.optional(),
-  query: z3.string().min(1).max(4096).describe("Metric DSL string, e.g. `count_users(checkout_completed)`.")
-});
-var experimentNameSchema = z3.string().regex(/^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$/).max(128).describe(
-  "Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create."
-);
-var experimentGroupSchema = z3.object({
-  name: z3.string().min(1).max(64).describe("Group label (e.g. `control`, `treatment_a`). Max 64 chars."),
-  weight: z3.number().int().min(0).max(1e4).describe(
-    "Allocation weight in basis points (0\u201310000). The sum across all groups must equal exactly **10000** (100%)."
-  ),
-  params: z3.record(z3.string(), z3.unknown()).default({}).describe(
-    "Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema."
-  )
-}).describe("One variant in the experiment. Weights across all groups must sum to 10000.");
-var paramSchemaSchema = z3.record(z3.string(), z3.enum(["string", "bool", "number"])).describe(
-  "Map of param-name \u2192 scalar type. Defines the shape of `groups[].params`. Example: `{ headline: 'string', show_cta: 'bool' }`."
-);
-var bucketBySchema = z3.string().min(1).max(128).regex(
-  /^[a-zA-Z_][a-zA-Z0-9_]*$/,
-  "Must be a user-attribute name (letters, digits, underscore; not starting with a digit)."
-).describe(
-  "User-attribute name used as the bucketing key \u2014 e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted."
-);
-var experimentCreateSchema = z3.object({
-  name: experimentNameSchema,
-  description: z3.string().max(2e3).nullable().default(null).describe("Free-form description. Max 2000 chars, markdown rendered in the dashboard."),
-  hypothesis: z3.string().max(4e3).nullable().default(null).describe("Hypothesis statement shown in the editor. Display-only."),
-  tag: z3.string().max(64).nullable().default(null).describe("Short tag chip rendered next to the name. Display-only."),
-  owner_email: z3.string().max(254).nullable().default(null).describe("Owner email. Display-only."),
-  audience: z3.string().max(256).nullable().default(null).describe("Audience label shown in the editor. Display-only."),
-  bucket_by: bucketBySchema.nullable().default(null),
-  folder: folderSchema,
-  universe: z3.string().min(1).describe(
-    "Name of an existing universe in the project. Returns `422` if the universe doesn't exist."
-  ),
-  targeting_gate: z3.string().nullable().default(null).describe(
-    "Optional gate name. Only callers that pass the gate are enrolled in the experiment."
-  ),
-  allocation_pct: z3.number().int().min(0).max(1e4).default(0).describe(
-    "Share of the (gated) audience allocated to the experiment, in basis points (0\u201310000 = 0%\u2013100%). `0` = unallocated. Immutable while the experiment is running."
-  ),
-  salt: z3.string().min(1).max(64).optional().describe("Hash salt for bucketing. Auto-generated if omitted. Immutable while running."),
-  params: paramSchemaSchema.default({}),
-  groups: z3.array(experimentGroupSchema).min(2).describe(
-    "Two or more variants. Weights must sum to exactly 10000 (100%). Immutable while running."
-  ),
-  significance_threshold: z3.number().min(1e-4).max(0.5).default(0.05).describe(
-    "p-value cutoff used by the analysis pass. Defaults to `0.05`. Values other than 0.05 require Pro plan or higher."
-  ),
-  min_runtime_days: z3.number().int().min(0).max(365).default(0).describe("Minimum days the experiment must run before results are considered conclusive."),
-  min_sample_size: z3.number().int().min(1).default(100).describe("Minimum exposures per group before results are considered conclusive."),
-  sequential_testing: z3.boolean().default(false).describe(
-    "Enable sequential testing (always-valid p-values). Requires Premium plan or higher."
-  ),
-  goal_metric: experimentInlineMetricSchema.optional().describe(
-    "Single goal metric defined inline as a DSL query. The underlying event is auto-created if missing."
-  ),
-  guardrail_metrics: z3.array(experimentInlineMetricSchema).max(10).default([]).describe(
-    "Up to 10 guardrail metrics defined inline. Each is upserted (event + metric) and attached with role=guardrail."
-  )
-}).refine(
-  (e) => e.groups.reduce((s, g) => s + g.weight, 0) === 1e4,
-  "groups weights must sum to exactly 10000"
-).describe(
-  "Body for `POST /api/admin/experiments`. `name`, `universe`, and `groups` (\u22652, weights sum to 10000) required."
-);
-var experimentUpdateSchema = z3.object({
-  name: experimentNameSchema.optional(),
-  description: z3.string().max(2e3).nullable().optional(),
-  hypothesis: z3.string().max(4e3).nullable().optional(),
-  tag: z3.string().max(64).nullable().optional(),
-  owner_email: z3.string().max(254).nullable().optional(),
-  audience: z3.string().max(256).nullable().optional(),
-  bucket_by: bucketBySchema.nullable().optional(),
-  folder: folderSchema,
-  targeting_gate: z3.string().nullable().optional(),
-  allocation_pct: z3.number().int().min(0).max(1e4).optional().describe("Basis-points allocation (0\u201310000). Immutable while the experiment is running."),
-  salt: z3.string().min(1).max(64).optional().describe("Hash salt. Immutable while running."),
-  universe: z3.string().optional().describe(
-    "New universe name. Immutable while running. Returns `422` if the universe doesn't exist."
-  ),
-  params: paramSchemaSchema.optional(),
-  groups: z3.array(experimentGroupSchema).min(2).optional().describe("Replacement groups. Weights must sum to 10000. Immutable while running."),
-  significance_threshold: z3.number().min(1e-4).max(0.5).optional(),
-  min_runtime_days: z3.number().int().min(0).max(365).optional(),
-  min_sample_size: z3.number().int().min(1).optional(),
-  sequential_testing: z3.boolean().optional(),
-  goal_metric: experimentInlineMetricSchema.optional().describe("Replaces the goal metric (event auto-upserted)."),
-  guardrail_metrics: z3.array(experimentInlineMetricSchema).max(10).optional().describe("Replaces the guardrail set wholesale (event auto-upserted per entry).")
-}).describe(
-  "Body for `PATCH /api/admin/experiments/{id}`. Partial \u2014 only supplied fields change. `allocation_pct`, `groups`, `salt`, `universe`, `params` are immutable while the experiment is running (stop first)."
-);
-var experimentStatusUpdateSchema = z3.object({
-  status: z3.enum(["draft", "running", "stopped", "archived"]).describe(
-    "Target status. Allowed transitions: `draft \u2192 running`, `running \u2192 stopped`, `stopped \u2192 archived`, `draft \u2192 archived`, and `archived \u2192 draft` (restore \u2014 only if the experiment never started). Restarting an archived experiment directly is not allowed; restore it to draft first, then start."
-  )
-}).describe("Body for `POST /api/admin/experiments/{id}/status`.");
-var experimentMetricsUpdateSchema = z3.object({
-  metrics: z3.array(
-    z3.object({
-      metric_id: z3.string().describe("Existing metric id in the project."),
-      role: z3.enum(["goal", "guardrail", "secondary"]).describe(
-        "Metric role. `goal` drives the decision, `guardrail` blocks ship if degraded, `secondary` is informational."
-      )
-    })
-  ).describe("Replacement metrics list \u2014 replaces the current attachments wholesale.")
-}).describe(
-  "Body for `POST /api/admin/experiments/{id}/metrics`. Replaces the experiment's metric attachments wholesale. Returns `422` if any `metric_id` is unknown."
-);
-var experimentResponseSchema = z3.object({
-  id: z3.string().describe("Stable opaque experiment id (`exp_\u2026`)."),
-  name: experimentNameSchema,
-  description: z3.string().nullable(),
-  hypothesis: z3.string().nullable(),
-  tag: z3.string().nullable(),
-  ownerEmail: z3.string().nullable(),
-  audience: z3.string().nullable(),
-  bucketBy: bucketBySchema.nullable(),
-  folder: z3.string().nullable(),
-  status: z3.enum(["draft", "running", "stopped", "archived"]),
-  universe: z3.string().describe("Universe name this experiment draws from."),
-  targetingGate: z3.string().nullable(),
-  allocationPct: z3.number().int().describe("Allocation in basis points (0\u201310000)."),
-  salt: z3.string(),
-  params: z3.record(z3.string(), z3.enum(["string", "bool", "number"])),
-  groups: z3.array(experimentGroupSchema),
-  significanceThreshold: z3.number(),
-  minRuntimeDays: z3.number().int(),
-  minSampleSize: z3.number().int(),
-  sequentialTesting: z3.boolean(),
-  startedAt: z3.string().nullable().describe("ISO-8601 timestamp the experiment last transitioned to `running`, or `null`."),
-  stoppedAt: z3.string().nullable().optional(),
-  updatedAt: z3.string()
-});
-var experimentCreateResponseSchema = z3.object({
-  id: z3.string().describe("Newly assigned experiment id."),
-  name: experimentNameSchema
-});
-var experimentUpdateResponseSchema = z3.object({
-  id: z3.string().describe("Experiment id that was updated.")
-});
-var experimentDeleteResponseSchema = z3.object({ ok: z3.literal(true) });
-var experimentStatusResponseSchema = z3.object({
-  id: z3.string(),
-  status: z3.enum(["draft", "running", "stopped", "archived"])
-});
-var experimentMetricsResponseSchema = z3.object({
-  id: z3.string(),
-  metrics: z3.array(
-    z3.object({
-      metric_id: z3.string(),
-      role: z3.enum(["goal", "guardrail", "secondary"])
-    })
-  )
-});
-var experimentResultRowSchema = z3.object({
-  metric: z3.string(),
-  group_name: z3.string(),
-  ds: z3.string().describe("Date slice (`YYYY-MM-DD`)."),
-  n: z3.number().nullable(),
-  mean: z3.number().nullable(),
-  delta_pct: z3.number().nullable(),
-  p_value: z3.number().nullable(),
-  srm_detected: z3.number().nullable().describe("`1` if sample-ratio mismatch detected, else `0`.")
-});
-var experimentResultsResponseSchema = z3.object({
-  experiment: z3.object({
-    id: z3.string(),
-    name: experimentNameSchema,
-    status: z3.enum(["draft", "running", "stopped", "archived"])
-  }),
-  results: z3.array(experimentResultRowSchema)
-});
-var experimentTimeseriesResponseSchema = z3.object({
-  experiment: z3.object({
-    id: z3.string(),
-    name: experimentNameSchema,
-    status: z3.enum(["draft", "running", "stopped", "archived"])
-  }),
-  series: z3.array(experimentResultRowSchema)
-});
-var experimentReanalyzeResponseSchema = z3.object({
-  id: z3.string(),
-  queued: z3.literal(true)
-});
-
-// src/transport.ts
-var ApiError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "ApiError";
-  }
-  status;
-};
-
-// src/resources/experiments.ts
-var experimentListResponseSchema = z4.object({
-  data: z4.array(experimentResponseSchema),
-  next_cursor: z4.string().nullable()
-});
-var BASE = "/api/admin/experiments";
-function experimentsClient(t) {
-  async function list(opts = {}) {
-    const query = {};
-    if (opts.limit !== void 0) query.limit = String(opts.limit);
-    if (opts.cursor) query.cursor = opts.cursor;
-    return t.request("GET", BASE, void 0, query);
-  }
-  async function listAllWith(status) {
-    const out = [];
-    let cursor;
-    do {
-      const query = { limit: "500" };
-      if (cursor) query.cursor = cursor;
-      if (status) query.status = status;
-      const page = await t.request("GET", BASE, void 0, query);
-      out.push(...page.data);
-      cursor = page.next_cursor ?? void 0;
-    } while (cursor);
-    return out;
-  }
-  async function listAll() {
-    return listAllWith();
-  }
-  async function resolve(idOrName) {
-    try {
-      return await t.request("GET", `${BASE}/${idOrName}`);
-    } catch (err) {
-      if (!(err instanceof ApiError) || err.status !== 404) throw err;
-    }
-    const found = (await listAllWith()).find((e) => e.name === idOrName) ?? (await listAllWith("archived")).find((e) => e.name === idOrName);
-    if (!found) throw new ApiError(`Experiment '${idOrName}' not found`, 404);
-    return found;
-  }
-  async function setStatus(id, status) {
-    return t.request(
-      "POST",
-      `${BASE}/${id}/status`,
-      experimentStatusUpdateSchema.parse({ status })
-    );
-  }
-  return {
-    list,
-    listAll,
-    resolve,
-    get: (id) => t.request("GET", `${BASE}/${id}`),
-    create: (input) => t.request("POST", BASE, experimentCreateSchema.parse(input)),
-    update: (id, input) => t.request("PATCH", `${BASE}/${id}`, experimentUpdateSchema.parse(input)),
-    delete: (id) => t.request("DELETE", `${BASE}/${id}`),
-    setStatus,
-    start: (id) => setStatus(id, "running"),
-    stop: (id) => setStatus(id, "stopped"),
-    archive: (id) => setStatus(id, "archived"),
-    restore: (id) => setStatus(id, "draft"),
-    setMetrics: (id, input) => t.request("POST", `${BASE}/${id}/metrics`, experimentMetricsUpdateSchema.parse(input)),
-    results: (id) => t.request("GET", `${BASE}/${id}/results`),
-    timeseries: (id, metric) => t.request(
-      "GET",
-      `${BASE}/${id}/timeseries`,
-      void 0,
-      metric ? { metric } : void 0
-    ),
-    reanalyze: (id) => t.request("POST", `${BASE}/${id}/reanalyze`)
-  };
-}
-var SAMPLE_EXP = {
-  id: "exp_01j7wb12c3d4e5f6g7h8j9k0l1",
-  name: "checkout_button_color",
-  description: "Test green vs. blue CTA on the checkout page.",
-  tag: "checkout",
-  status: "running",
-  universe: "primary_users",
-  targetingGate: null,
-  allocationPct: 5e3,
-  salt: "8d3e9a1f6b7c4a5fa1c2b6d3e7c8e3a1",
-  params: { cta_color: "string" },
-  groups: [
-    { name: "control", weight: 5e3, params: { cta_color: "blue" } },
-    { name: "treatment", weight: 5e3, params: { cta_color: "green" } }
-  ],
-  significanceThreshold: 0.05,
-  minRuntimeDays: 7,
-  minSampleSize: 1e3,
-  sequentialTesting: false,
-  startedAt: "2026-05-01T12:00:00.000Z",
-  stoppedAt: null,
-  updatedAt: "2026-05-09T18:22:11.000Z"
-};
-var experimentsResource = {
-  name: "experiments",
-  basePath: BASE,
-  describeOne: "experiment",
-  describeMany: "experiments",
-  tag: {
-    name: "Experiments",
-    description: [
-      "A/B/n experiments: randomised group assignment plus the analysis pipeline (t-test, sequential testing, SRM detection) on top of a universe.",
-      "",
-      "**Identity.** Stable `name` (a-z, 0-9, `_`/`-`, max 64 chars). Immutable after create.",
-      "",
-      "**Lifecycle.** `draft \u2192 running \u2192 stopped \u2192 archived`. Transition via `POST /{id}/status`. An archived experiment that never started can be restored with `archived \u2192 draft`; restarting an archived experiment directly is not allowed.",
-      "",
-      "**Allocation.** `allocation_pct` (basis points, 0\u201310000) is the share of the targeted audience enrolled; `groups[].weight` (must sum to 10000) splits the enrolled audience. `targeting_gate` narrows the eligible audience before allocation.",
-      "",
-      "**Immutable while running.** `allocation_pct`, `groups`, `salt`, `universe`, `params` cannot be edited on a running experiment \u2014 stop it first.",
-      "",
-      "**Metrics.** Attach via `POST /{id}/metrics`. Each metric has a role: `goal` drives the decision, `guardrail` blocks ship on regression, `secondary` is informational.",
-      "",
-      "**Analysis.** Daily cron writes results to D1. Read via `GET /{id}/results` (latest per metric/group/day) or `GET /{id}/timeseries` (full history). `POST /{id}/reanalyze` requeues the analysis pass."
-    ].join("\n")
-  },
-  schemas: {
-    create: experimentCreateSchema,
-    update: experimentUpdateSchema
-  },
-  actions: [
-    { name: "start", description: "Transition draft experiment to running" },
-    { name: "stop", description: "Stop a running experiment" },
-    { name: "archive", description: "Archive a stopped experiment" },
-    { name: "restore", description: "Restore an archived (never-started) experiment to draft" },
-    { name: "reanalyze", description: "Re-run analysis pass for the experiment" }
-  ],
-  endpoints: [
-    {
-      operationId: "listExperiments",
-      method: "GET",
-      path: "",
-      summary: "List experiments",
-      description: "Returns a single page of non-archived experiments ordered by `updated_at desc, id desc`. Use the `cursor` query parameter to paginate.",
-      response: experimentListResponseSchema,
-      examples: { response: { data: [SAMPLE_EXP], next_cursor: null } },
-      useCase: "Snapshot every active experiment in the project \u2014 e.g. render an overview dashboard or drive a CI check that no experiment has been running past its `min_runtime_days`."
-    },
-    {
-      operationId: "getExperiment",
-      method: "GET",
-      path: "/{id}",
-      summary: "Get one experiment",
-      description: "Returns the full experiment row including groups, params, allocation, and lifecycle timestamps.",
-      pathParams: { id: "Stable opaque experiment id (`exp_\u2026`) or the experiment's `name`." },
-      response: experimentResponseSchema,
-      examples: { response: SAMPLE_EXP },
-      useCase: "Fetch one experiment to render the detail page or to inspect its current allocation and group weights."
-    },
-    {
-      operationId: "createExperiment",
-      method: "POST",
-      path: "",
-      summary: "Create an experiment",
-      description: [
-        "Creates a new experiment in `draft` status. `name`, `universe`, and `groups` are required; everything else has sensible defaults.",
-        "",
-        "Returns `409` if `name` already exists, `422` if the named universe doesn't exist, `403` if a plan-gated option is set (`sequential_testing`, custom `significance_threshold`) on a plan that doesn't include it."
-      ].join("\n"),
-      successStatus: 201,
-      request: experimentCreateSchema,
-      response: experimentCreateResponseSchema,
-      examples: {
-        requestExamples: {
-          minimal: {
-            summary: "Minimal \u2014 two-group 50/50",
-            description: "Smallest valid body. Two groups at 50/50, no allocation, no targeting.",
-            value: {
-              name: "checkout_button_color",
-              universe: "primary_users",
-              groups: [
-                { name: "control", weight: 5e3 },
-                { name: "treatment", weight: 5e3 }
-              ]
-            }
-          },
-          targeted: {
-            summary: "Targeted \u2014 gate + allocation + params",
-            description: "Gate the audience with a `targeting_gate`, allocate 50% of it, and parameterise the variants.",
-            value: {
-              name: "checkout_button_color",
-              description: "Green CTA on checkout for Pro users.",
-              universe: "primary_users",
-              targeting_gate: "pro_plan_only",
-              allocation_pct: 5e3,
-              params: { cta_color: "string" },
-              groups: [
-                { name: "control", weight: 5e3, params: { cta_color: "blue" } },
-                { name: "treatment", weight: 5e3, params: { cta_color: "green" } }
-              ]
-            }
-          },
-          multivariant: {
-            summary: "Multivariant \u2014 three groups",
-            description: "Three variants splitting 40/30/30. Requires the sum to equal 10000.",
-            value: {
-              name: "headline_test",
-              universe: "primary_users",
-              groups: [
-                { name: "control", weight: 4e3 },
-                { name: "alt_a", weight: 3e3 },
-                { name: "alt_b", weight: 3e3 }
-              ]
-            }
-          },
-          sequential: {
-            summary: "Sequential testing \u2014 Premium plan",
-            description: "Enable always-valid sequential tests. Requires Premium plan or higher.",
-            value: {
-              name: "checkout_button_color",
-              universe: "primary_users",
-              groups: [
-                { name: "control", weight: 5e3 },
-                { name: "treatment", weight: 5e3 }
-              ],
-              sequential_testing: true,
-              min_runtime_days: 14
-            }
-          }
-        },
-        response: { id: "exp_01j7wb12c3d4e5f6g7h8j9k0l1", name: "checkout_button_color" }
-      },
-      useCase: [
-        "- **Minimal 50/50** \u2014 `name` + `universe` + two equal-weight groups.",
-        "- **Targeted rollout** \u2014 supply `targeting_gate` to restrict the eligible audience and `allocation_pct` to enrol a slice of it.",
-        "- **Multivariant** \u2014 three or more groups with weights summing to 10000.",
-        "- **Sequential testing** \u2014 `sequential_testing: true` for Premium plans."
-      ].join("\n")
-    },
-    {
-      operationId: "updateExperiment",
-      method: "PATCH",
-      path: "/{id}",
-      summary: "Update an experiment",
-      description: [
-        "Partial update. `allocation_pct`, `groups`, `salt`, `universe`, `params` are **immutable while running** \u2014 returns `409` if you try. Stop the experiment first.",
-        "",
-        "Editing `groups` while in `draft` is fine; weights must still sum to 10000."
-      ].join("\n"),
-      pathParams: { id: "Stable opaque experiment id." },
-      request: experimentUpdateSchema,
-      response: experimentUpdateResponseSchema,
-      examples: {
-        requestExamples: {
-          rampAllocation: {
-            summary: "Ramp allocation \u2014 0 \u2192 50%",
-            description: "Bumps the share of the targeted audience enrolled. Allowed only when the experiment is in `draft`.",
-            value: { allocation_pct: 5e3 }
-          },
-          changeWeights: {
-            summary: "Change group weights",
-            description: "Replace the groups array \u2014 weights must still sum to 10000.",
-            value: {
-              groups: [
-                { name: "control", weight: 2500 },
-                { name: "treatment", weight: 7500 }
-              ]
-            }
-          },
-          tighterSignificance: {
-            summary: "Tighter significance threshold",
-            description: "Drop the p-value cutoff from 0.05 \u2192 0.01. Requires Pro plan or higher.",
-            value: { significance_threshold: 0.01 }
-          },
-          updateMetadata: {
-            summary: "Update metadata",
-            description: "Change description/tag/targeting_gate freely on running experiments.",
-            value: {
-              description: "Bumped to 50% after passing canary on 25%.",
-              tag: "checkout"
-            }
-          }
-        },
-        response: { id: "exp_01j7wb12c3d4e5f6g7h8j9k0l1" }
-      },
-      useCase: [
-        "- **Update metadata** \u2014 `description`, `tag`, `targeting_gate` editable any time.",
-        "- **Ramp before launch** \u2014 set `allocation_pct` while still in `draft`.",
-        "- **Tighten significance** \u2014 `significance_threshold` (Pro+).",
-        "- **Rewire groups** \u2014 replace `groups` wholesale while in `draft`; immutable once running."
-      ].join("\n")
-    },
-    {
-      operationId: "deleteExperiment",
-      method: "DELETE",
-      path: "/{id}",
-      summary: "Delete an experiment",
-      description: "Archives the experiment (soft-delete via status transition). Returns `409` if the experiment is still `running` \u2014 stop it first.",
-      pathParams: { id: "Stable opaque experiment id." },
-      response: experimentDeleteResponseSchema,
-      examples: { response: { ok: true } },
-      useCase: "Tear down an experiment after the analysis is signed off."
-    },
-    {
-      operationId: "setExperimentStatus",
-      method: "POST",
-      path: "/{id}/status",
-      summary: "Transition experiment status",
-      description: [
-        "Drives the experiment lifecycle. Allowed transitions:",
-        "",
-        "- `draft \u2192 running` \u2014 starts allocation. Bumps the `startedAt` timestamp.",
-        "- `running \u2192 stopped` \u2014 halts allocation. Existing exposures stay in the dataset.",
-        "- `stopped \u2192 archived` \u2014 soft-delete.",
-        "- `draft \u2192 archived` \u2014 discard an unstarted experiment.",
-        "- `archived \u2192 draft` \u2014 restore a soft-deleted experiment so it can be re-completed and started. Allowed only if it never started; one that already ran must be cloned instead.",
-        "",
-        "Restarting an `archived` experiment directly is not allowed \u2014 restore it to `draft` first. Returns `409` on illegal transitions and `429` if the plan's `experiments_running` limit is exceeded on `\u2192 running`."
-      ].join("\n"),
-      pathParams: { id: "Stable opaque experiment id." },
-      request: experimentStatusUpdateSchema,
-      response: experimentStatusResponseSchema,
-      examples: {
-        requestExamples: {
-          start: {
-            summary: "Start \u2014 draft \u2192 running",
-            description: "Begins allocation. The experiment counts against the plan's `experiments_running` limit.",
-            value: { status: "running" }
-          },
-          stop: {
-            summary: "Stop \u2014 running \u2192 stopped",
-            description: "Halts allocation. Existing exposures remain analysable.",
-            value: { status: "stopped" }
-          },
-          archive: {
-            summary: "Archive \u2014 stopped \u2192 archived",
-            description: "Soft-deletes the experiment. List endpoints exclude archived rows by default.",
-            value: { status: "archived" }
-          },
-          restore: {
-            summary: "Restore \u2014 archived \u2192 draft",
-            description: "Un-deletes a soft-deleted experiment so it can be re-completed and started. Allowed only if it never ran.",
-            value: { status: "draft" }
-          }
-        },
-        response: { id: "exp_01j7wb12c3d4e5f6g7h8j9k0l1", status: "running" }
-      },
-      useCase: [
-        '- **Start** \u2014 `{ "status": "running" }` after wiring up the SDK and verifying targeting on staging.',
-        '- **Stop** \u2014 `{ "status": "stopped" }` once the experiment hits its `min_runtime_days` and conclusive results land.',
-        '- **Archive** \u2014 `{ "status": "archived" }` to soft-delete after sign-off.'
-      ].join("\n")
-    },
-    {
-      operationId: "setExperimentMetrics",
-      method: "POST",
-      path: "/{id}/metrics",
-      summary: "Attach metrics",
-      description: [
-        "Replaces the experiment's metric attachments wholesale. Each entry pairs an existing `metric_id` with a `role` (`goal` / `guardrail` / `secondary`).",
-        "",
-        "Returns `422` if any `metric_id` doesn't exist in the project. Pass `{ metrics: [] }` to detach everything."
-      ].join("\n"),
-      pathParams: { id: "Stable opaque experiment id." },
-      request: experimentMetricsUpdateSchema,
-      response: experimentMetricsResponseSchema,
-      examples: {
-        requestExamples: {
-          standard: {
-            summary: "Standard \u2014 one goal + one guardrail",
-            description: "Attaches one decision metric and one safety metric.",
-            value: {
-              metrics: [
-                { metric_id: "met_checkout_completed", role: "goal" },
-                { metric_id: "met_page_errors", role: "guardrail" }
-              ]
-            }
-          },
-          detach: {
-            summary: "Detach all",
-            description: "Send an empty array to clear every metric.",
-            value: { metrics: [] }
-          }
-        },
-        response: {
-          id: "exp_01j7wb12c3d4e5f6g7h8j9k0l1",
-          metrics: [
-            { metric_id: "met_checkout_completed", role: "goal" },
-            { metric_id: "met_page_errors", role: "guardrail" }
-          ]
-        }
-      },
-      useCase: [
-        "- **Standard setup** \u2014 one `goal`, one or two `guardrail`, optional `secondary` metrics for diagnostics.",
-        '- **Detach all** \u2014 send `{ "metrics": [] }` before archiving.'
-      ].join("\n")
-    },
-    {
-      operationId: "getExperimentResults",
-      method: "GET",
-      path: "/{id}/results",
-      summary: "Get analysis results",
-      description: "Returns the latest analysis output for the experiment \u2014 one row per metric/group/day, including sample size, mean, % delta vs. control, p-value, and a sample-ratio mismatch flag.",
-      pathParams: { id: "Stable opaque experiment id." },
-      response: experimentResultsResponseSchema,
-      examples: {
-        response: {
-          experiment: {
-            id: "exp_01j7wb12c3d4e5f6g7h8j9k0l1",
-            name: "checkout_button_color",
-            status: "running"
-          },
-          results: [
-            {
-              metric: "checkout_completed",
-              group_name: "control",
-              ds: "2026-05-09",
-              n: 12421,
-              mean: 0.1834,
-              delta_pct: null,
-              p_value: null,
-              srm_detected: 0
-            },
-            {
-              metric: "checkout_completed",
-              group_name: "treatment",
-              ds: "2026-05-09",
-              n: 12519,
-              mean: 0.1922,
-              delta_pct: 4.8,
-              p_value: 0.018,
-              srm_detected: 0
-            }
-          ]
-        }
-      },
-      useCase: "Render the results table on the experiment detail page or drive an automated decision once a `goal` metric reaches significance."
-    },
-    {
-      operationId: "getExperimentTimeseries",
-      method: "GET",
-      path: "/{id}/timeseries",
-      summary: "Get analysis timeseries",
-      description: "Same row shape as `/results`, but returns every daily slice rather than the latest. Filter to a single metric with the `metric` query parameter.",
-      pathParams: { id: "Stable opaque experiment id." },
-      queryParams: {
-        metric: {
-          schema: z4.string().optional(),
-          description: "Optional metric name to filter the series."
-        }
-      },
-      response: experimentTimeseriesResponseSchema,
-      examples: {
-        response: {
-          experiment: {
-            id: "exp_01j7wb12c3d4e5f6g7h8j9k0l1",
-            name: "checkout_button_color",
-            status: "running"
-          },
-          series: [
-            {
-              metric: "checkout_completed",
-              group_name: "treatment",
-              ds: "2026-05-08",
-              n: 11200,
-              mean: 0.1903,
-              delta_pct: 3.9,
-              p_value: 0.034,
-              srm_detected: 0
-            },
-            {
-              metric: "checkout_completed",
-              group_name: "treatment",
-              ds: "2026-05-09",
-              n: 12519,
-              mean: 0.1922,
-              delta_pct: 4.8,
-              p_value: 0.018,
-              srm_detected: 0
-            }
-          ]
-        }
-      },
-      useCase: "Drive a chart of metric movement over the experiment runtime, or sanity-check the lift is monotonic before deciding."
-    },
-    {
-      operationId: "reanalyzeExperiment",
-      method: "POST",
-      path: "/{id}/reanalyze",
-      summary: "Re-queue analysis",
-      description: "Requeues the daily analysis pass for this experiment outside the normal cron cadence. Useful after attaching a new metric or correcting an event taxonomy. The job runs asynchronously.",
-      pathParams: { id: "Stable opaque experiment id." },
-      response: experimentReanalyzeResponseSchema,
-      examples: { response: { id: "exp_01j7wb12c3d4e5f6g7h8j9k0l1", queued: true } },
-      useCase: "Force-refresh results after wiring up a new metric without waiting for the next nightly cron tick."
-    }
-  ]
-};
-export {
-  experimentsClient,
-  experimentsResource
-};