@shipeasy/openapi 1.5.0 → 1.6.0

package/dist/operations/types.d.ts

@@ -0,0 +1,138 @@
+import { AdminClient } from '../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';
+
+/**
+ * Operation registry — the single source of truth that drives BOTH
+ * `@shipeasy/cli` (commander subcommands) and `@shipeasy/mcp` (MCP tools),
+ * plus their generated docs.
+ *
+ * Today each surface is hand-maintained: the CLI hand-builds commander
+ * commands in `packages/cli/src/commands/*`, the MCP server hand-writes tool
+ * JSON Schemas in `packages/mcp/src/tools/schema.ts` and a 60-branch dispatch
+ * in `server.ts`, and the percent→basis-points + `JSON.parse(rules)` mapping
+ * is written *identically* in both. An Operation collapses that into one
+ * definition: the params describe the ergonomic facade once, `run` performs
+ * the facade→wire mapping once, and the adapters in this folder project it
+ * onto each surface.
+ */
+/** Param value kinds. `json` arrives as a JSON string on both surfaces and is parsed by the framework. */
+type ParamType = "string" | "number" | "boolean" | "json";
+interface Param {
+    /** Field name — also the CLI flag (`--<name>`) or positional, and the MCP property key. */
+    name: string;
+    type: ParamType;
+    /** Shown in CLI `--help`, the MCP tool input schema, and generated docs. */
+    description: string;
+    required?: boolean;
+    /** CLI only: render as a positional `<name>` argument instead of a `--flag`. Ignored by MCP. */
+    positional?: boolean;
+    /** Restrict to a fixed set (MCP `enum`, CLI validated in coercion). */
+    enum?: string[];
+}
+interface OpExample {
+    /** Why you'd run this. */
+    note?: string;
+    /** A copy-pasteable command line. */
+    run: string;
+}
+/** Coerced facade input handed to `run` — keys are param names, values coerced by `ParamType`. */
+type OpInput = Record<string, unknown>;
+interface Operation<O = unknown> {
+    /**
+     * Command-path segments BEFORE the verb, e.g. `["release", "flags"]`.
+     * This is the exact CLI nesting; nested resources just add segments
+     * (`["release", "experiments", "universes"]`). Drives grouping + naming.
+     */
+    group: string[];
+    /**
+     * The verb, e.g. `create`. Authored ONCE — every surface name derives from
+     * `group` + `name` so they can never drift:
+     *   id  = `release.flags.create`   (opId   — `.`-joined)
+     *   CLI = `release flags create`   (opCli  — space-joined, the real invocation)
+     *   MCP = `release_flags_create`   (opMcpName — `_`-joined; MCP names can't have spaces)
+     */
+    name: string;
+    /** True for writes — the CLI/MCP adapter enforces `.shipeasy` binding before running. */
+    mutates: boolean;
+    /** One-liner — CLI `.description()` and the docs heading. */
+    summary: string;
+    /** Long-form — the MCP tool `description` and the docs body. */
+    description: string;
+    params: Param[];
+    examples?: OpExample[];
+    /**
+     * The single source of behaviour: coerced facade input → typed AdminClient
+     * call → raw data. Returns data (never prints) so every surface can format
+     * it its own way (CLI table, MCP JSON envelope, …).
+     */
+    run: (client: AdminClient, input: OpInput) => Promise<O>;
+}
+/**
+ * Structural subset of commander's `Command`. The CLI adapter targets this so
+ * `@shipeasy/openapi` never has to depend on `commander` — commander's real
+ * `Command` satisfies it.
+ */
+interface CommandLike {
+    command(nameAndArgs: string): CommandLike;
+    description(text: string): CommandLike;
+    option(flags: string, description?: string, defaultValue?: unknown): CommandLike;
+    action(fn: (...args: unknown[]) => void | Promise<void>): CommandLike;
+}
+/** Everything the CLI surface injects so the adapter stays free of process/chalk/IO. */
+interface CliContext {
+    /** Resolve the typed admin client; `mutates` triggers the `requireBinding` guard. */
+    getClient: (o: {
+        mutates: boolean;
+        projectOverride?: string;
+    }) => AdminClient;
+    /** Print machine output (`--json`). */
+    printJson: (data: unknown) => void;
+    /** Print human output for a successful op (table / one-liner). */
+    printResult: (op: Operation, data: unknown, input: OpInput) => void;
+    /** Terminal error handler (prints + exits). */
+    onError: (e: unknown) => void;
+}
+type Named = Pick<Operation, "group" | "name">;
+/** Stable id, e.g. `release.flags.create`. */
+declare const opId: (op: Named) => string;
+/** MCP tool name, e.g. `release_flags_create` — the CLI path with `_` for each space. */
+declare const opMcpName: (op: Named) => string;
+/** CLI invocation, e.g. `release flags create` (full command path). */
+declare const opCli: (op: Named) => string;
+/** Plain MCP `Tool` shape — structurally compatible with `@modelcontextprotocol/sdk`'s `Tool`. */
+interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        required?: string[];
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+        }>;
+    };
+}
+
+export { type CliContext, type CommandLike, type McpTool, type OpExample, type OpInput, type Operation, type Param, type ParamType, opCli, opId, opMcpName };

package/dist/operations/types.js

@@ -0,0 +1,9 @@
+// src/operations/types.ts
+var opId = (op) => [...op.group, op.name].join(".");
+var opMcpName = (op) => [...op.group, op.name].join("_");
+var opCli = (op) => [...op.group, op.name].join(" ");
+export {
+  opCli,
+  opId,
+  opMcpName
+};

package/dist/operations/universes.d.ts

@@ -0,0 +1,28 @@
+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 universeOperations: Operation[];
+
+export { universeOperations };

package/dist/operations/universes.js

@@ -0,0 +1,93 @@
+// src/transport.ts
+var ApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+  }
+  status;
+};
+
+// src/operations/util.ts
+var str = (i, k) => i[k] === void 0 ? void 0 : i[k];
+
+// src/operations/universes.ts
+var GROUP = ["release", "experiments", "universes"];
+function parseHoldout(raw) {
+  if (raw === void 0 || raw === "" || raw === "null") return null;
+  const [lo, hi] = raw.split(",").map((s) => Number(s.trim()));
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) {
+    throw new ApiError("holdout must be 'lo,hi' integers in [0,9999]", 400);
+  }
+  return [lo, hi];
+}
+var universeOperations = [
+  {
+    group: GROUP,
+    name: "list",
+    mutates: false,
+    summary: "List universes",
+    description: "Return every experiment universe (allocation %, holdout %).",
+    params: [],
+    examples: [{ run: "shipeasy release experiments universes list" }],
+    run: (client) => client.universes.listAll()
+  },
+  {
+    group: GROUP,
+    name: "create",
+    mutates: true,
+    summary: "Create a universe",
+    description: "Create an experiment universe (container + optional holdout).",
+    params: [
+      { name: "name", type: "string", description: "Universe name.", required: true, positional: true },
+      { name: "unitType", type: "string", description: "Unit type (e.g. user_id, account_id). Defaults to user_id." },
+      { name: "holdout", type: "string", description: "Holdout range as 'lo,hi' (0\u20139999); omit for no holdout." }
+    ],
+    examples: [
+      { note: "Default user_id unit, no holdout", run: "shipeasy release experiments universes create web" },
+      { note: "Holdout 0\u2013999, keyed on account_id", run: "shipeasy release experiments universes create web --unit-type account_id --holdout 0,999" }
+    ],
+    run: (client, i) => client.universes.create({
+      name: i.name,
+      unit_type: str(i, "unitType") ?? "user_id",
+      holdout_range: parseHoldout(str(i, "holdout"))
+    })
+  },
+  {
+    group: GROUP,
+    name: "update",
+    mutates: true,
+    summary: "Update a universe's holdout range",
+    description: "Update the holdout range. Pass 'null' to clear the holdout.",
+    params: [
+      { name: "name", type: "string", description: "Universe name.", required: true, positional: true },
+      { name: "holdout", type: "string", description: "Holdout range as 'lo,hi' (0\u20139999), or 'null' to clear." }
+    ],
+    examples: [
+      { note: "Set a 5% holdout", run: "shipeasy release experiments universes update web --holdout 0,499" },
+      { note: "Clear the holdout", run: "shipeasy release experiments universes update web --holdout null" }
+    ],
+    run: async (client, i) => {
+      const x = await client.universes.resolve(i.name);
+      const patch = i.holdout === void 0 ? {} : { holdout_range: parseHoldout(str(i, "holdout")) };
+      return client.universes.update(x.id, patch);
+    }
+  },
+  {
+    group: GROUP,
+    name: "archive",
+    mutates: true,
+    summary: "Archive a universe",
+    description: "Archive (soft-delete) a universe by name.",
+    params: [{ name: "name", type: "string", description: "Universe name.", required: true, positional: true }],
+    examples: [{ run: "shipeasy release experiments universes archive web" }],
+    run: async (client, i) => {
+      const x = await client.universes.resolve(i.name);
+      await client.universes.delete(x.id);
+      return { ok: true, archived: i.name };
+    }
+  }
+];
+export {
+  universeOperations
+};

package/dist/operations/util.d.ts

@@ -0,0 +1,33 @@
+import { 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';
+
+/** Read a coerced number param (already `Number()`-ed by the framework), or undefined. */
+declare const num: (i: OpInput, k: string) => number | undefined;
+/** Read a string param, or undefined. */
+declare const str: (i: OpInput, k: string) => string | undefined;
+/** Read a boolean param, or undefined. */
+declare const bool: (i: OpInput, k: string) => boolean | undefined;
+
+export { bool, num, str };

package/dist/operations/util.js

@@ -0,0 +1,9 @@
+// src/operations/util.ts
+var num = (i, k) => i[k] === void 0 ? void 0 : i[k];
+var str = (i, k) => i[k] === void 0 ? void 0 : i[k];
+var bool = (i, k) => i[k] === void 0 ? void 0 : i[k];
+export {
+  bool,
+  num,
+  str
+};

package/dist/resources/attributes.d.ts

@@ -0,0 +1,19 @@
+import { Transport } from '../transport.js';
+
+/**
+ * Targeting attributes — the auto-inferred user-attribute schema the dashboard
+ * surfaces for gate/experiment targeting. Read-only; this exists so the typed
+ * `attributes list` op can replace the `attributes` kind of the old MCP-only
+ * "generic read" (`list_resources`), which is being deleted (see doc 21 §A4.3).
+ */
+interface Attribute {
+    name: string;
+    type?: string;
+    [key: string]: unknown;
+}
+interface AttributesClient {
+    list(): Promise<Attribute[]>;
+}
+declare function attributesClient(t: Transport): AttributesClient;
+
+export { type Attribute, type AttributesClient, attributesClient };

package/dist/resources/attributes.js

@@ -0,0 +1,10 @@
+// src/resources/attributes.ts
+var BASE = "/api/admin/attributes";
+function attributesClient(t) {
+  return {
+    list: () => t.request("GET", BASE)
+  };
+}
+export {
+  attributesClient
+};

package/dist/resources/events.d.ts

@@ -0,0 +1,61 @@
+import { Transport } from '../transport.js';
+
+/**
+ * Event catalog — the registry of event names (and their typed properties) that
+ * metric queries reference. `/collect` auto-discovers unknown names as
+ * `pending` rows; `approve` promotes them to usable. Property `name:type`
+ * parsing is a CLI/MCP facade concern; the resource takes the already-parsed
+ * `properties` array.
+ */
+interface EventProperty {
+    name: string;
+    type: "string" | "number" | "boolean";
+    required: boolean;
+    description?: string;
+}
+interface CatalogEvent {
+    id: string;
+    name: string;
+    folder: string | null;
+    description: string | null;
+    properties: EventProperty[];
+    pending: number;
+    createdAt: string;
+    [key: string]: unknown;
+}
+interface EventCreateInput {
+    name: string;
+    folder?: string | null;
+    description?: string;
+    properties?: EventProperty[];
+}
+interface EventUpdateInput {
+    folder?: string | null;
+    description?: string;
+    /** Replaces the full property set (no merge). */
+    properties?: EventProperty[];
+}
+interface EventsClient {
+    list(): Promise<CatalogEvent[]>;
+    get(id: string): Promise<CatalogEvent>;
+    create(input: EventCreateInput): Promise<{
+        id: string;
+        name: string;
+    }>;
+    update(id: string, input: EventUpdateInput): Promise<{
+        id: string;
+    }>;
+    /** Promote a pending (auto-discovered) event so metrics can query it. */
+    approve(id: string, input?: EventUpdateInput): Promise<{
+        id: string;
+    }>;
+    /** Soft-delete (the user-facing verb is `archive`). */
+    delete(id: string): Promise<{
+        ok: true;
+    }>;
+    /** Resolve by exact id, unique id-prefix, or exact (unique) name. */
+    resolve(idOrName: string): Promise<CatalogEvent>;
+}
+declare function eventsClient(t: Transport): EventsClient;
+
+export { type CatalogEvent, type EventCreateInput, type EventProperty, type EventUpdateInput, type EventsClient, eventsClient };

package/dist/resources/events.js

@@ -0,0 +1,42 @@
+// src/transport.ts
+var ApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+  }
+  status;
+};
+
+// src/resources/events.ts
+var BASE = "/api/admin/events";
+function eventsClient(t) {
+  async function list() {
+    return t.request("GET", BASE);
+  }
+  async function resolve(idOrName) {
+    const all = await list();
+    const byId = all.find((e) => e.id === idOrName);
+    if (byId) return byId;
+    const byPrefix = all.filter((e) => e.id.startsWith(idOrName));
+    if (byPrefix.length === 1) return byPrefix[0];
+    if (byPrefix.length > 1) throw new ApiError(`Event id prefix '${idOrName}' is ambiguous`, 400);
+    const byName = all.filter((e) => e.name === idOrName);
+    if (byName.length === 1) return byName[0];
+    if (byName.length > 1)
+      throw new ApiError(`Event name '${idOrName}' is ambiguous \u2014 pass an id`, 400);
+    throw new ApiError(`Event '${idOrName}' not found`, 404);
+  }
+  return {
+    list,
+    resolve,
+    get: (id) => t.request("GET", `${BASE}/${id}`),
+    create: (input) => t.request("POST", BASE, input),
+    update: (id, input) => t.request("PATCH", `${BASE}/${id}`, input),
+    approve: (id, input = {}) => t.request("POST", `${BASE}/${id}/approve`, input),
+    delete: (id) => t.request("DELETE", `${BASE}/${id}`)
+  };
+}
+export {
+  eventsClient
+};

package/dist/resources/i18n.d.ts

@@ -0,0 +1,84 @@
+import { Transport } from '../transport.js';
+
+/**
+ * i18n (String Manager) — the API-only parts that are worker-safe and shared
+ * between CLI and MCP: locale profiles, the insert-only key push, single-key
+ * update, chunk publish, and the read-only key/draft listings.
+ *
+ * The fs/AST parts (`scan`, `validate`, `install-loader`, `codemod`) stay
+ * hand-written in the fs-having consumers and are NEVER added here — the
+ * registry is bundled into a Worker that can't load `node:fs` or the TS AST.
+ */
+interface I18nProfile {
+    id: string;
+    name: string;
+    locales?: string[];
+    default_locale?: string;
+}
+interface I18nKey {
+    id: string;
+    key: string;
+    value?: string;
+    [key: string]: unknown;
+}
+interface I18nDraft {
+    id: string;
+    [key: string]: unknown;
+}
+interface I18nPushResult {
+    added?: string[];
+    skipped?: string[];
+    pushed_count?: number;
+    skipped_count?: number;
+}
+interface I18nClient {
+    listProfiles(): Promise<I18nProfile[]>;
+    createProfile(input: {
+        name: string;
+        locales?: string[];
+        default_locale?: string;
+    }): Promise<{
+        id: string;
+        name: string;
+    }>;
+    /** Resolve a profile by exact name (the user-facing handle). */
+    resolveProfile(name: string): Promise<I18nProfile>;
+    /** Insert-only key push (existing keys are left untouched). */
+    pushKeys(input: {
+        profile_id: string;
+        chunk?: string;
+        keys: {
+            key: string;
+            value: string;
+        }[];
+    }): Promise<I18nPushResult>;
+    /** List keys for a profile (optionally a name prefix). */
+    listKeys(query?: {
+        profile_id?: string;
+        prefix?: string;
+        limit?: number;
+    }): Promise<I18nKey[]>;
+    /** Update one existing key's value (the only overwrite path). */
+    updateKey(id: string, input: {
+        value: string;
+        description?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** Resolve a key by exact name within a profile, then PUT its new value. */
+    updateKeyByName(profileId: string, key: string, input: {
+        value: string;
+        description?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** List staged drafts (the read-only `drafts` kind from the old generic read). */
+    listDrafts(): Promise<I18nDraft[]>;
+    /** Publish a profile chunk (rebuild KV manifest + purge CDN). */
+    publish(profileId: string, input: {
+        chunk?: string;
+    }): Promise<unknown>;
+}
+declare function i18nClient(t: Transport): I18nClient;
+
+export { type I18nClient, type I18nDraft, type I18nKey, type I18nProfile, type I18nPushResult, i18nClient };

package/dist/resources/i18n.js

@@ -0,0 +1,60 @@
+// src/transport.ts
+var ApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+  }
+  status;
+};
+
+// src/resources/i18n.ts
+var PROFILES = "/api/admin/i18n/profiles";
+var KEYS = "/api/admin/i18n/keys";
+var DRAFTS = "/api/admin/i18n/drafts";
+function i18nClient(t) {
+  async function listProfiles() {
+    return t.request("GET", PROFILES);
+  }
+  async function resolveProfile(name) {
+    const all = await listProfiles();
+    const found = all.find((p) => p.name === name);
+    if (!found)
+      throw new ApiError(
+        `Profile '${name}' not found. Existing: ${all.map((p) => p.name).join(", ") || "(none)"}`,
+        404
+      );
+    return found;
+  }
+  async function listKeys(query = {}) {
+    const q = {};
+    if (query.profile_id) q.profile_id = query.profile_id;
+    if (query.prefix) q.prefix = query.prefix;
+    if (query.limit !== void 0) q.limit = String(query.limit);
+    const res = await t.request("GET", KEYS, void 0, q);
+    return Array.isArray(res) ? res : res.keys;
+  }
+  function updateKey(id, input) {
+    return t.request("PUT", `${KEYS}/${id}`, input);
+  }
+  return {
+    listProfiles,
+    resolveProfile,
+    listKeys,
+    updateKey,
+    createProfile: (input) => t.request("POST", PROFILES, input),
+    pushKeys: (input) => t.request("POST", KEYS, input),
+    updateKeyByName: async (profileId, key, input) => {
+      const rows = await listKeys({ profile_id: profileId, prefix: key, limit: 500 });
+      const match = rows.find((k) => k.key === key);
+      if (!match)
+        throw new ApiError(`Key '${key}' not found in profile. Add it first with i18n push.`, 404);
+      return updateKey(match.id, input);
+    },
+    listDrafts: () => t.request("GET", DRAFTS),
+    publish: (profileId, input) => t.request("POST", `${PROFILES}/${profileId}/publish`, { chunk: input.chunk ?? "default" })
+  };
+}
+export {
+  i18nClient
+};

package/dist/resources/index.d.ts

@@ -1,7 +1,17 @@
-import { Transport } from '../transport.js';
-import '../schemas/pagination.js';
 import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
+import { AttributesClient } from './attributes.js';
+export { attributesClient } from './attributes.js';
+import { I18nClient } from './i18n.js';
+export { i18nClient } from './i18n.js';
+import { ProjectsClient } from './projects.js';
+export { projectsClient } from './projects.js';
+import { OpsClient } from './ops.js';
+export { opsClient } from './ops.js';
+import { EventsClient } from './events.js';
+export { eventsClient } from './events.js';
+import { MetricsClient } from './metrics.js';
+export { metricsClient } from './metrics.js';
 import { AlertRulesClient } from './alert-rules.js';
 export { alertRulesClient } from './alert-rules.js';
 import { KillswitchesClient } from './killswitches.js';
@@ -14,12 +24,14 @@ import { ExperimentsClient } from './experiments.js';
 export { experimentsClient, experimentsResource } from './experiments.js';
 import { GatesClient } from './gates.js';
 export { gatesClient, gatesResource } from './gates.js';
-import '../schemas/gates.js';
-import '../schemas/universes.js';
+import { Transport } from '../transport.js';
 import '../schemas/alert-rules.js';
 import '../schemas/killswitches.js';
+import '../schemas/pagination.js';
+import '../schemas/universes.js';
 import '../schemas/configs.js';
 import '../schemas/experiments.js';
+import '../schemas/gates.js';
 
 /**
  * Aggregate admin client. Each resource lives in its own file under
@@ -36,6 +48,12 @@ declare function createAdminClient(transport: Transport): {
     universes: UniversesClient;
     killswitches: KillswitchesClient;
     alertRules: AlertRulesClient;
+    metrics: MetricsClient;
+    events: EventsClient;
+    ops: OpsClient;
+    projects: ProjectsClient;
+    i18n: I18nClient;
+    attributes: AttributesClient;
 };
 type AdminClient = ReturnType<typeof createAdminClient>;
 /**