@shipeasy/openapi 1.6.0 → 2.2.0

package/spec/paths/search.yaml

@@ -0,0 +1,62 @@
+/api/admin/search:
+  get:
+    operationId: searchResources
+    summary: Search project resources
+    description: |-
+      Universal substring search across the project's primary resources — feature gates, experiments, dynamic configs, killswitches, metrics, and team members. Matches the trimmed `q` against each resource's immutable `name` and its human title/display name (members match on display name or email), newest-first, capped per resource family so one noisy type can't crowd out the rest.
+
+      Returns a flat, ranked-by-type list of hits (members first); an empty or whitespace-only `q` returns no hits. Each hit carries a project-relative `href` that deep-links to the row.
+
+      **Use case:** Back a command-palette / quick-switcher in the dashboard, or look up the id of a resource by a fragment of its name before driving another API call.
+    tags:
+      - Projects
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: q
+        in: query
+        required: false
+        description: Search query. Matched as a case-insensitive substring against each resource's `name` and title/display name. Trimmed; empty returns no hits.
+        schema:
+          type: string
+    responses:
+      "200":
+        description: Search project resources
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/search.yaml#/SearchResponse
+            example:
+              hits:
+                - type: member
+                  id: ana@example.com
+                  name: Ana Ng
+                  title: ana@example.com
+                  href: /team
+                - type: gate
+                  id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
+                  name: checkout_v2
+                  title: Checkout v2
+                  href: /gates?open=gat_01j7w7m9q4hxbf6npe6s9zr3vc
+                - type: experiment
+                  id: exp_01j7w7m9q4hxbf6npe6s9zr3vd
+                  name: checkout_button_color
+                  title: Checkout button colour test
+                  href: /experiments?open=exp_01j7w7m9q4hxbf6npe6s9zr3vd
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: search

package/spec/paths/universes.yaml

@@ -0,0 +1,255 @@
+/api/admin/universes:
+  get:
+    operationId: listUniverses
+    summary: List universes
+    description: |-
+      Returns a single page of universes ordered by `created_at desc, id desc`. The universes table has no `updated_at`, so this list is keyed on creation time.
+
+      **Use case:** Snapshot every universe in the project — for example to audit which `unit_type` and `holdout_range` are in use before launching a new experiment.
+    tags:
+      - Universes
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/PaginationLimit
+      - $ref: ../components/parameters.yaml#/PaginationCursor
+      - $ref: ../components/parameters.yaml#/Q
+    responses:
+      "200":
+        description: List universes
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/universes.yaml#/ListUniversesResponse
+            example:
+              data:
+                - id: uni_01j7w8a1b2c3d4e5f6g7h8i9j0
+                  name: primary_users
+                  unitType: user_id
+                  holdoutRange:
+                    - 9500
+                    - 9999
+                  createdAt: 2026-04-12T10:14:08.000Z
+              next_cursor: null
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: list
+  post:
+    operationId: createUniverse
+    summary: Create a universe
+    description: |-
+      Creates a new universe. Only `name` is required — `unit_type` defaults to `user_id` and `holdout_range` defaults to `null` (no holdout).
+
+      Returns `409` if `name` already exists in the project. Returns `403` if you supply `holdout_range` on a plan below Pro.
+
+      **Use cases**
+
+      - **Default universe** — `{ "name": "primary_users" }`. Per-user randomisation, no holdout.
+      - **Reserved holdout** — supply `holdout_range` to carve out a measurement slice excluded from all experiments.
+      - **Account-level** — `unit_type: 'account_id'` so multi-seat accounts see one consistent variant.
+    tags:
+      - Universes
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/universes.yaml#/CreateUniverseRequest
+          examples:
+            minimal:
+              summary: Minimal — name only
+              description: Smallest valid body. Creates a `user_id`-keyed universe with no holdout.
+              value:
+                name: primary_users
+            holdout:
+              summary: Holdout — reserve 5% for measurement
+              description: Reserves buckets 9500–9999 (5% of callers) as the holdout. Pro plan or higher.
+              value:
+                name: primary_users
+                holdout_range:
+                  - 9500
+                  - 9999
+            accountLevel:
+              summary: Account-level randomisation
+              description: "Bucket whole accounts together via `unit_type: 'account_id'`."
+              value:
+                name: saas_accounts
+                unit_type: account_id
+    responses:
+      "201":
+        description: Create a universe
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/universes.yaml#/CreateUniverseResponse
+            example:
+              id: uni_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: primary_users
+        links:
+          UpdateUniverse:
+            operationId: updateUniverse
+            parameters: { id: $response.body#/id }
+          DeleteUniverse:
+            operationId: deleteUniverse
+            parameters: { id: $response.body#/id }
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - PLAN_REQUIRED
+      - ALREADY_EXISTS
+      - VALIDATION
+    x-cli:
+      name: create
+      positional:
+        - name
+/api/admin/universes/{id}:
+  patch:
+    operationId: updateUniverse
+    summary: Update a universe
+    description: |-
+      Partial update. Only `holdout_range` is mutable — `name` and `unit_type` are immutable after create.
+
+      Pass `"holdout_range": null` to remove an existing holdout.
+
+      **Use cases**
+
+      - **Adjust holdout** — change the reserved measurement slice without recreating experiments.
+      - **Remove holdout** — `{ "holdout_range": null }`.
+    tags:
+      - Universes
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque universe id (`uni_…`) or the universe's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/universes.yaml#/UpdateUniverseRequest
+          examples:
+            setHoldout:
+              summary: Set holdout — reserve 5%
+              description: Reserve buckets 9500–9999 as the holdout. Pro plan or higher.
+              value:
+                holdout_range:
+                  - 9500
+                  - 9999
+            removeHoldout:
+              summary: Remove holdout
+              description: Disable the holdout entirely.
+              value:
+                holdout_range: null
+    responses:
+      "200":
+        description: Update a universe
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/universes.yaml#/UpdateUniverseResponse
+            example:
+              id: uni_01j7w8a1b2c3d4e5f6g7h8i9j0
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - PLAN_REQUIRED
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - id
+  delete:
+    operationId: deleteUniverse
+    summary: Delete a universe
+    description: |-
+      Soft-deletes the universe. Returns `409` if any non-archived experiment still references it — archive those experiments first.
+
+      **Use case:** Tear down a universe after every experiment that used it has been archived.
+    tags:
+      - Universes
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque universe id (`uni_…`) or the universe's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Delete a universe
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/universes.yaml#/DeleteUniverseResponse
+            example:
+              ok: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - REFERENCED_IN_USE
+    x-cli:
+      name: archive
+      positional:
+        - id

package/dist/operations/attributes.d.ts

@@ -1,33 +0,0 @@
-import { Operation } from './types.js';
-import '../resources/index.js';
-import 'zod/v4/core';
-import 'zod';
-import '../resources/attributes.js';
-import '../transport.js';
-import '../resources/i18n.js';
-import '../resources/projects.js';
-import '../resources/ops.js';
-import '../resources/events.js';
-import '../resources/metrics.js';
-import '../resources/alert-rules.js';
-import '../schemas/alert-rules.js';
-import '../resources/killswitches.js';
-import '../schemas/killswitches.js';
-import '../schemas/pagination.js';
-import '../resources/universes.js';
-import '../schemas/universes.js';
-import '../resources/configs.js';
-import '../schemas/configs.js';
-import '../resources/experiments.js';
-import '../schemas/experiments.js';
-import '../resources/gates.js';
-import '../schemas/gates.js';
-
-/**
- * Attribute operations — `attributes …`. One read-only op so the typed
- * `attributes_list` MCP tool replaces the `attributes` kind of the deleted
- * generic-read path (doc 21 §A4.3).
- */
-declare const attributeOperations: Operation[];
-
-export { attributeOperations };

package/dist/operations/attributes.js

@@ -1,16 +0,0 @@
-// src/operations/attributes.ts
-var attributeOperations = [
-  {
-    group: ["attributes"],
-    name: "list",
-    mutates: false,
-    summary: "List targeting attributes",
-    description: "List the auto-inferred user-attribute schema available for gate/experiment targeting.",
-    params: [],
-    examples: [{ run: "shipeasy attributes list" }],
-    run: (client) => client.attributes.list()
-  }
-];
-export {
-  attributeOperations
-};

package/dist/operations/cli-adapter.d.ts

@@ -1,35 +0,0 @@
-import { CommandLike, Operation, CliContext } from './types.js';
-import '../resources/index.js';
-import 'zod/v4/core';
-import 'zod';
-import '../resources/attributes.js';
-import '../transport.js';
-import '../resources/i18n.js';
-import '../resources/projects.js';
-import '../resources/ops.js';
-import '../resources/events.js';
-import '../resources/metrics.js';
-import '../resources/alert-rules.js';
-import '../schemas/alert-rules.js';
-import '../resources/killswitches.js';
-import '../schemas/killswitches.js';
-import '../schemas/pagination.js';
-import '../resources/universes.js';
-import '../schemas/universes.js';
-import '../resources/configs.js';
-import '../schemas/configs.js';
-import '../resources/experiments.js';
-import '../schemas/experiments.js';
-import '../resources/gates.js';
-import '../schemas/gates.js';
-
-/**
- * Mount every operation as a commander subcommand under `group`. The CLI passes
- * its own commander `Command` (which satisfies `CommandLike`) and a `CliContext`
- * carrying the bits `@shipeasy/openapi` must not own (client resolution, table
- * formatting, process.exit). Replaces the per-command hand-wiring in
- * `packages/cli/src/commands/*`.
- */
-declare function mountOperations(group: CommandLike, ops: Operation[], ctx: CliContext): void;
-
-export { mountOperations };

package/dist/operations/cli-adapter.js

@@ -1,91 +0,0 @@
-// src/transport.ts
-var ApiError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "ApiError";
-  }
-  status;
-};
-
-// src/operations/coerce.ts
-function coerceValue(param, raw) {
-  if (raw === void 0 || raw === null) return void 0;
-  switch (param.type) {
-    case "number": {
-      const n = typeof raw === "number" ? raw : Number(raw);
-      if (!Number.isFinite(n)) throw new ApiError(`--${param.name} must be a number`, 400);
-      return n;
-    }
-    case "boolean":
-      return raw === true || raw === "true" || raw === "1";
-    case "json":
-      if (typeof raw !== "string") return raw;
-      try {
-        return JSON.parse(raw);
-      } catch {
-        throw new ApiError(`--${param.name} must be valid JSON`, 400);
-      }
-    case "string":
-    default: {
-      const s = String(raw);
-      if (param.enum && !param.enum.includes(s)) {
-        throw new ApiError(`--${param.name} must be one of: ${param.enum.join(", ")}`, 400);
-      }
-      return s;
-    }
-  }
-}
-function coerceInput(op, raw) {
-  const out = {};
-  for (const param of op.params) {
-    const value = coerceValue(param, raw[param.name]);
-    if (value === void 0) {
-      if (param.required) throw new ApiError(`${param.name} is required`, 400);
-      continue;
-    }
-    out[param.name] = value;
-  }
-  return out;
-}
-
-// src/operations/cli-adapter.ts
-var toKebab = (s) => s.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
-function commandSignature(op) {
-  const positionals = op.params.filter((p) => p.positional).map((p) => p.required === false ? `[${p.name}]` : `<${p.name}>`);
-  return [op.name, ...positionals].join(" ");
-}
-function mountOperations(group, ops, ctx) {
-  for (const op of ops) {
-    const positionals = op.params.filter((p) => p.positional);
-    const flags = op.params.filter((p) => !p.positional);
-    const cmd = group.command(commandSignature(op)).description(op.summary);
-    for (const p of flags) {
-      cmd.option(`--${toKebab(p.name)} <value>`, p.description);
-    }
-    cmd.option("--json", "Output as JSON");
-    cmd.option("--project <id>", "Project ID override");
-    cmd.action(async (...argv) => {
-      try {
-        const opts = argv.find((a) => a && typeof a === "object" && !Array.isArray(a)) ?? {};
-        const raw = { ...opts };
-        positionals.forEach((p, i) => {
-          raw[p.name] = argv[i];
-        });
-        const input = coerceInput(op, raw);
-        const client = ctx.getClient({
-          mutates: op.mutates,
-          projectOverride: opts.project
-        });
-        const data = await op.run(client, input);
-        if (opts.json) ctx.printJson(data);
-        else ctx.printResult(op, data, input);
-      } catch (e) {
-        ctx.onError(e);
-      }
-    });
-  }
-}
-export {
-  mountOperations
-};

package/dist/operations/coerce.d.ts

@@ -1,32 +0,0 @@
-import { Operation, OpInput } from './types.js';
-import '../resources/index.js';
-import 'zod/v4/core';
-import 'zod';
-import '../resources/attributes.js';
-import '../transport.js';
-import '../resources/i18n.js';
-import '../resources/projects.js';
-import '../resources/ops.js';
-import '../resources/events.js';
-import '../resources/metrics.js';
-import '../resources/alert-rules.js';
-import '../schemas/alert-rules.js';
-import '../resources/killswitches.js';
-import '../schemas/killswitches.js';
-import '../schemas/pagination.js';
-import '../resources/universes.js';
-import '../schemas/universes.js';
-import '../resources/configs.js';
-import '../schemas/configs.js';
-import '../resources/experiments.js';
-import '../schemas/experiments.js';
-import '../resources/gates.js';
-import '../schemas/gates.js';
-
-/**
- * Build the coerced facade input `run` expects from a raw key→value bag
- * (commander's merged args+opts, or MCP's `arguments`). Enforces `required`.
- */
-declare function coerceInput(op: Operation, raw: Record<string, unknown>): OpInput;
-
-export { coerceInput };

package/dist/operations/coerce.js

@@ -1,53 +0,0 @@
-// src/transport.ts
-var ApiError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "ApiError";
-  }
-  status;
-};
-
-// src/operations/coerce.ts
-function coerceValue(param, raw) {
-  if (raw === void 0 || raw === null) return void 0;
-  switch (param.type) {
-    case "number": {
-      const n = typeof raw === "number" ? raw : Number(raw);
-      if (!Number.isFinite(n)) throw new ApiError(`--${param.name} must be a number`, 400);
-      return n;
-    }
-    case "boolean":
-      return raw === true || raw === "true" || raw === "1";
-    case "json":
-      if (typeof raw !== "string") return raw;
-      try {
-        return JSON.parse(raw);
-      } catch {
-        throw new ApiError(`--${param.name} must be valid JSON`, 400);
-      }
-    case "string":
-    default: {
-      const s = String(raw);
-      if (param.enum && !param.enum.includes(s)) {
-        throw new ApiError(`--${param.name} must be one of: ${param.enum.join(", ")}`, 400);
-      }
-      return s;
-    }
-  }
-}
-function coerceInput(op, raw) {
-  const out = {};
-  for (const param of op.params) {
-    const value = coerceValue(param, raw[param.name]);
-    if (value === void 0) {
-      if (param.required) throw new ApiError(`${param.name} is required`, 400);
-      continue;
-    }
-    out[param.name] = value;
-  }
-  return out;
-}
-export {
-  coerceInput
-};

package/dist/operations/configs.d.ts

@@ -1,28 +0,0 @@
-import { Operation } from './types.js';
-import '../resources/index.js';
-import 'zod/v4/core';
-import 'zod';
-import '../resources/attributes.js';
-import '../transport.js';
-import '../resources/i18n.js';
-import '../resources/projects.js';
-import '../resources/ops.js';
-import '../resources/events.js';
-import '../resources/metrics.js';
-import '../resources/alert-rules.js';
-import '../schemas/alert-rules.js';
-import '../resources/killswitches.js';
-import '../schemas/killswitches.js';
-import '../schemas/pagination.js';
-import '../resources/universes.js';
-import '../schemas/universes.js';
-import '../resources/configs.js';
-import '../schemas/configs.js';
-import '../resources/experiments.js';
-import '../schemas/experiments.js';
-import '../resources/gates.js';
-import '../schemas/gates.js';
-
-declare const configOperations: Operation[];
-
-export { configOperations };