@shipeasy/openapi 1.5.0 → 2.1.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,247 @@
+/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
+    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
+      "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:
+          type: string
+    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:
+          type: string
+    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/resources/alert-rules.d.ts

@@ -1,50 +0,0 @@
-import { z } from 'zod';
-import { NotificationTarget, alertRuleCreateSchema, alertRuleUpdateSchema } from '../schemas/alert-rules.js';
-import { Transport } from '../transport.js';
-
-type AlertRuleCreateInput = z.input<typeof alertRuleCreateSchema>;
-type AlertRuleUpdateInput = z.input<typeof alertRuleUpdateSchema>;
-/**
- * One metric-threshold alert rule. The cron evaluates `agg(metric)` over the
- * trailing `windowHours` and raises an alert at `severity` when the value
- * `comparator` `threshold` holds.
- *
- * `metricId` is fixed at create time — there is no update path for it (the
- * metric also pins the aggregation). Tune `threshold`/`comparator`/
- * `windowHours`/`severity`/`name`/`enabled` instead, or delete + recreate to
- * repoint the rule at a different metric.
- */
-interface AlertRule {
-    id: string;
-    name: string;
-    metricId: string;
-    metricName: string | null;
-    comparator: "gt" | "gte" | "lt" | "lte";
-    threshold: number;
-    windowHours: number;
-    severity: "danger" | "warn" | "info";
-    enabled: boolean;
-    /** Delivery target for this rule's alert; null = use project default. */
-    notify: NotificationTarget | null;
-    createdAt: string;
-    updatedAt: string;
-}
-interface AlertRulesClient {
-    /** All alert rules for the bound project (the list endpoint is not paginated). */
-    list(): Promise<AlertRule[]>;
-    /** Resolve a rule by exact id, unique id-prefix, or exact (unique) name. */
-    resolve(idOrName: string): Promise<AlertRule>;
-    create(input: AlertRuleCreateInput): Promise<{
-        id: string;
-    }>;
-    /** Patch tunable knobs. `metricId` is rejected by the schema (immutable). */
-    update(id: string, input: AlertRuleUpdateInput): Promise<{
-        id: string;
-    }>;
-    delete(id: string): Promise<{
-        ok: true;
-    }>;
-}
-declare function alertRulesClient(t: Transport): AlertRulesClient;
-
-export { type AlertRule, type AlertRuleCreateInput, type AlertRuleUpdateInput, type AlertRulesClient, alertRulesClient };

package/dist/resources/alert-rules.js

@@ -1,75 +0,0 @@
-// src/schemas/alert-rules.ts
-import { z } from "zod";
-var ALERT_COMPARATORS = ["gt", "gte", "lt", "lte"];
-var ALERT_SEVERITIES = ["danger", "warn", "info"];
-var notificationTargetSchema = z.object({
-  slackChannel: z.object({
-    id: z.string().min(1).describe("Slack channel id (e.g. C0123ABCD)."),
-    name: z.string().min(1).describe("Slack channel name (without the leading #).")
-  }).nullish().describe("Slack channel to post this rule's alert to. Requires a Slack connector."),
-  email: z.string().email().nullish().describe("Email address to notify for this rule (overrides the default recipient).")
-}).strict();
-var alertRuleCreateSchema = z.object({
-  name: z.string().min(1).max(120).describe("Human label for the rule, shown on the alert and the rules list."),
-  metricId: z.string().min(1).describe("Id of the metric to evaluate."),
-  comparator: z.enum(ALERT_COMPARATORS).describe("How the metric value is compared to the threshold (gt/gte/lt/lte)."),
-  threshold: z.number().finite().describe("Threshold the metric value is compared against."),
-  windowHours: z.number().int().min(1).max(720).default(24).describe("Lookback window (hours) the metric is aggregated over. 1\u2013720."),
-  severity: z.enum(ALERT_SEVERITIES).default("warn").describe("Severity of the raised alert."),
-  enabled: z.boolean().default(true).describe("Whether the rule is evaluated by the cron."),
-  notify: notificationTargetSchema.nullish().describe("Where to deliver this rule's alert (Slack channel and/or email target).")
-}).strict();
-var alertRuleUpdateSchema = z.object({
-  name: z.string().min(1).max(120),
-  comparator: z.enum(ALERT_COMPARATORS),
-  threshold: z.number().finite(),
-  windowHours: z.number().int().min(1).max(720),
-  severity: z.enum(ALERT_SEVERITIES),
-  enabled: z.boolean(),
-  notify: notificationTargetSchema.nullish()
-}).partial().strict();
-
-// src/transport.ts
-var ApiError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "ApiError";
-  }
-  status;
-};
-
-// src/resources/alert-rules.ts
-var BASE = "/api/admin/alert-rules";
-function alertRulesClient(t) {
-  async function list() {
-    return t.request("GET", BASE);
-  }
-  async function resolve(idOrName) {
-    const all = await list();
-    const byId = all.find((r) => r.id === idOrName);
-    if (byId) return byId;
-    const byPrefix = all.filter((r) => r.id.startsWith(idOrName));
-    if (byPrefix.length === 1) return byPrefix[0];
-    if (byPrefix.length > 1)
-      throw new ApiError(`Alert rule id prefix '${idOrName}' is ambiguous`, 400);
-    const byName = all.filter((r) => r.name === idOrName);
-    if (byName.length === 1) return byName[0];
-    if (byName.length > 1)
-      throw new ApiError(
-        `Alert rule name '${idOrName}' is ambiguous \u2014 pass an id instead`,
-        400
-      );
-    throw new ApiError(`Alert rule '${idOrName}' not found`, 404);
-  }
-  return {
-    list,
-    resolve,
-    create: (input) => t.request("POST", BASE, alertRuleCreateSchema.parse(input)),
-    update: (id, input) => t.request("PATCH", `${BASE}/${id}`, alertRuleUpdateSchema.parse(input)),
-    delete: (id) => t.request("DELETE", `${BASE}/${id}`)
-  };
-}
-export {
-  alertRulesClient
-};