@shipeasy/openapi 1.0.0

package/dist/resources/universes.d.ts

@@ -0,0 +1,182 @@
+import { z } from 'zod';
+import { UniverseCreateInput, UniverseUpdateInput } from '@shipeasy/core/schemas/universes';
+export { UniverseCreateInput, UniverseUpdateInput } from '@shipeasy/core/schemas/universes';
+import { PageQuery, Page } from '@shipeasy/core/pagination';
+import { Transport } from '../transport.js';
+
+interface Universe {
+    id: string;
+    name: string;
+    unitType: string;
+    holdoutRange: [number, number] | null;
+    allocationPct?: number;
+    holdoutPct?: number;
+    updatedAt?: string;
+}
+interface UniversesClient {
+    list(opts?: Partial<PageQuery>): Promise<Page<Universe>>;
+    listAll(): Promise<Universe[]>;
+    resolve(idOrName: string): Promise<Universe>;
+    create(input: UniverseCreateInput): Promise<Universe>;
+    update(id: string, input: UniverseUpdateInput): Promise<Universe>;
+    delete(id: string): Promise<{
+        ok: true;
+    }>;
+}
+declare function universesClient(t: Transport): UniversesClient;
+declare const universesResource: {
+    readonly name: "universes";
+    readonly basePath: "/api/admin/universes";
+    readonly describeOne: "universe";
+    readonly describeMany: "universes";
+    readonly tag: {
+        readonly name: "Universes";
+        readonly description: string;
+    };
+    readonly schemas: {
+        readonly create: z.ZodObject<{
+            name: z.ZodString;
+            unit_type: z.ZodDefault<z.ZodString>;
+            holdout_range: z.ZodDefault<z.ZodNullable<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+        }, z.core.$strip>;
+        readonly update: z.ZodObject<{
+            holdout_range: z.ZodOptional<z.ZodNullable<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+        }, z.core.$strip>;
+    };
+    readonly actions: readonly [];
+    readonly endpoints: readonly [{
+        readonly operationId: "listUniverses";
+        readonly method: "GET";
+        readonly path: "";
+        readonly summary: "List universes";
+        readonly 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.";
+        readonly response: z.ZodObject<{
+            data: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                unitType: z.ZodString;
+                holdoutRange: z.ZodNullable<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+                createdAt: z.ZodString;
+            }, z.core.$strip>>;
+            next_cursor: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        readonly examples: {
+            readonly response: {
+                readonly data: readonly [{
+                    readonly id: "uni_01j7w8a1b2c3d4e5f6g7h8i9j0";
+                    readonly name: "primary_users";
+                    readonly unitType: "user_id";
+                    readonly holdoutRange: readonly [9500, 9999];
+                    readonly createdAt: "2026-04-12T10:14:08.000Z";
+                }];
+                readonly next_cursor: null;
+            };
+        };
+        readonly useCase: "Snapshot every universe in the project — for example to audit which `unit_type` and `holdout_range` are in use before launching a new experiment.";
+    }, {
+        readonly operationId: "createUniverse";
+        readonly method: "POST";
+        readonly path: "";
+        readonly summary: "Create a universe";
+        readonly description: string;
+        readonly successStatus: 201;
+        readonly request: z.ZodObject<{
+            name: z.ZodString;
+            unit_type: z.ZodDefault<z.ZodString>;
+            holdout_range: z.ZodDefault<z.ZodNullable<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+        }, z.core.$strip>;
+        readonly response: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>;
+        readonly examples: {
+            readonly requestExamples: {
+                readonly minimal: {
+                    readonly summary: "Minimal — name only";
+                    readonly description: "Smallest valid body. Creates a `user_id`-keyed universe with no holdout.";
+                    readonly value: {
+                        readonly name: "primary_users";
+                    };
+                };
+                readonly holdout: {
+                    readonly summary: "Holdout — reserve 5% for measurement";
+                    readonly description: "Reserves buckets 9500–9999 (5% of callers) as the holdout. Pro plan or higher.";
+                    readonly value: {
+                        readonly name: "primary_users";
+                        readonly holdout_range: readonly [9500, 9999];
+                    };
+                };
+                readonly accountLevel: {
+                    readonly summary: "Account-level randomisation";
+                    readonly description: "Bucket whole accounts together via `unit_type: 'account_id'`.";
+                    readonly value: {
+                        readonly name: "saas_accounts";
+                        readonly unit_type: "account_id";
+                    };
+                };
+            };
+            readonly response: {
+                readonly id: "uni_01j7w8a1b2c3d4e5f6g7h8i9j0";
+                readonly name: "primary_users";
+            };
+        };
+        readonly useCase: string;
+    }, {
+        readonly operationId: "updateUniverse";
+        readonly method: "PATCH";
+        readonly path: "/{id}";
+        readonly summary: "Update a universe";
+        readonly description: string;
+        readonly pathParams: {
+            readonly id: "Stable opaque universe id (`uni_…`).";
+        };
+        readonly request: z.ZodObject<{
+            holdout_range: z.ZodOptional<z.ZodNullable<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+        }, z.core.$strip>;
+        readonly response: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+        readonly examples: {
+            readonly requestExamples: {
+                readonly setHoldout: {
+                    readonly summary: "Set holdout — reserve 5%";
+                    readonly description: "Reserve buckets 9500–9999 as the holdout. Pro plan or higher.";
+                    readonly value: {
+                        readonly holdout_range: readonly [9500, 9999];
+                    };
+                };
+                readonly removeHoldout: {
+                    readonly summary: "Remove holdout";
+                    readonly description: "Disable the holdout entirely.";
+                    readonly value: {
+                        readonly holdout_range: null;
+                    };
+                };
+            };
+            readonly response: {
+                readonly id: "uni_01j7w8a1b2c3d4e5f6g7h8i9j0";
+            };
+        };
+        readonly useCase: string;
+    }, {
+        readonly operationId: "deleteUniverse";
+        readonly method: "DELETE";
+        readonly path: "/{id}";
+        readonly summary: "Delete a universe";
+        readonly description: "Soft-deletes the universe. Returns `409` if any non-archived experiment still references it — archive those experiments first.";
+        readonly pathParams: {
+            readonly id: "Stable opaque universe id.";
+        };
+        readonly response: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+        readonly examples: {
+            readonly response: {
+                readonly ok: true;
+            };
+        };
+        readonly useCase: "Tear down a universe after every experiment that used it has been archived.";
+    }];
+};
+
+export { type Universe, type UniversesClient, universesClient, universesResource };

package/dist/resources/universes.js

@@ -0,0 +1,224 @@
+// src/resources/universes.ts
+import { z as z2 } from "zod";
+
+// ../core/src/schemas/universes.ts
+import { z } from "zod";
+var universeNameSchema = z.string().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/).describe(
+  "Stable universe key referenced by experiments via `universe: '<name>'`. Lowercase letters, digits, `_` or `-`, max 64 chars. Immutable after create."
+);
+var holdoutRangeSchema = z.tuple([z.number().int().min(0).max(9999), z.number().int().min(0).max(9999)]).refine(([lo, hi]) => lo <= hi, "lo must be <= hi").nullable().describe(
+  "Inclusive `[lo, hi]` bucket range (0\u20139999) reserved as the **holdout** \u2014 callers hashed into this slice are excluded from every experiment in the universe. `null` disables the holdout. Pro plan or higher required."
+);
+var universeCreateSchema = z.object({
+  name: universeNameSchema,
+  unit_type: z.string().default("user_id").describe(
+    "Unit of randomisation. Typically `user_id`. Use `account_id` to keep whole accounts in the same group across an experiment."
+  ),
+  holdout_range: holdoutRangeSchema.default(null)
+}).describe("Body for `POST /api/admin/universes`. Only `name` is required.");
+var universeUpdateSchema = z.object({
+  holdout_range: holdoutRangeSchema.optional()
+}).describe(
+  "Body for `PATCH /api/admin/universes/{id}`. Only `holdout_range` is mutable \u2014 name and unit_type are immutable after create."
+);
+var universeResponseSchema = z.object({
+  id: z.string().describe("Stable opaque universe id."),
+  name: universeNameSchema,
+  unitType: z.string().describe("Unit of randomisation. Snake-case in request (`unit_type`), camelCase in response."),
+  holdoutRange: z.tuple([z.number(), z.number()]).nullable().describe("Reserved holdout bucket range, or `null` if none."),
+  createdAt: z.string().describe("ISO-8601 timestamp of creation.")
+});
+var universeCreateResponseSchema = z.object({
+  id: z.string().describe("Newly assigned universe id."),
+  name: universeNameSchema
+});
+var universeUpdateResponseSchema = z.object({
+  id: z.string().describe("Universe id that was updated.")
+});
+var universeDeleteResponseSchema = z.object({ ok: z.literal(true) });
+
+// src/transport.ts
+var ApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+  }
+  status;
+};
+
+// src/resources/universes.ts
+var universeListResponseSchema = z2.object({
+  data: z2.array(universeResponseSchema),
+  next_cursor: z2.string().nullable()
+});
+var BASE = "/api/admin/universes";
+function universesClient(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 listAll() {
+    const out = [];
+    let cursor;
+    do {
+      const page = await list({ limit: 500, cursor });
+      out.push(...page.data);
+      cursor = page.next_cursor ?? void 0;
+    } while (cursor);
+    return out;
+  }
+  async function resolve(idOrName) {
+    const all = await listAll();
+    const found = all.find((u) => u.id === idOrName) ?? all.find((u) => u.name === idOrName);
+    if (!found) throw new ApiError(`Universe '${idOrName}' not found`, 404);
+    return found;
+  }
+  return {
+    list,
+    listAll,
+    resolve,
+    create: (input) => t.request("POST", BASE, universeCreateSchema.parse(input)),
+    update: (id, input) => t.request("PATCH", `${BASE}/${id}`, universeUpdateSchema.parse(input)),
+    delete: (id) => t.request("DELETE", `${BASE}/${id}`)
+  };
+}
+var universesResource = {
+  name: "universes",
+  basePath: BASE,
+  describeOne: "universe",
+  describeMany: "universes",
+  tag: {
+    name: "Universes",
+    description: [
+      "Universes: the shared bucketing space all experiments draw from.",
+      "",
+      "**Identity.** Each universe is keyed by a stable `name` (a-z, 0-9, `_`/`-`, max 64 chars). Experiments reference it via `universe: '<name>'`. The name is immutable.",
+      "",
+      "**Unit of randomisation.** `unit_type` selects the attribute hashed into a 0\u20139999 bucket \u2014 default `user_id` for per-user randomisation, `account_id` to keep a whole account in the same group.",
+      "",
+      "**Holdout.** `holdout_range` is an inclusive `[lo, hi]` bucket range (0\u20139999) reserved for measurement \u2014 callers hashed into the holdout are excluded from every experiment in the universe. Pro plan or higher.",
+      "",
+      "**Deletion.** Blocked while any non-archived experiment references the universe \u2014 archive those first."
+    ].join("\n")
+  },
+  schemas: {
+    create: universeCreateSchema,
+    update: universeUpdateSchema
+  },
+  actions: [],
+  endpoints: [
+    {
+      operationId: "listUniverses",
+      method: "GET",
+      path: "",
+      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.",
+      response: universeListResponseSchema,
+      examples: {
+        response: {
+          data: [
+            {
+              id: "uni_01j7w8a1b2c3d4e5f6g7h8i9j0",
+              name: "primary_users",
+              unitType: "user_id",
+              holdoutRange: [9500, 9999],
+              createdAt: "2026-04-12T10:14:08.000Z"
+            }
+          ],
+          next_cursor: null
+        }
+      },
+      useCase: "Snapshot every universe in the project \u2014 for example to audit which `unit_type` and `holdout_range` are in use before launching a new experiment."
+    },
+    {
+      operationId: "createUniverse",
+      method: "POST",
+      path: "",
+      summary: "Create a universe",
+      description: [
+        "Creates a new universe. Only `name` is required \u2014 `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."
+      ].join("\n"),
+      successStatus: 201,
+      request: universeCreateSchema,
+      response: universeCreateResponseSchema,
+      examples: {
+        requestExamples: {
+          minimal: {
+            summary: "Minimal \u2014 name only",
+            description: "Smallest valid body. Creates a `user_id`-keyed universe with no holdout.",
+            value: { name: "primary_users" }
+          },
+          holdout: {
+            summary: "Holdout \u2014 reserve 5% for measurement",
+            description: "Reserves buckets 9500\u20139999 (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" }
+          }
+        },
+        response: { id: "uni_01j7w8a1b2c3d4e5f6g7h8i9j0", name: "primary_users" }
+      },
+      useCase: [
+        '- **Default universe** \u2014 `{ "name": "primary_users" }`. Per-user randomisation, no holdout.',
+        "- **Reserved holdout** \u2014 supply `holdout_range` to carve out a measurement slice excluded from all experiments.",
+        "- **Account-level** \u2014 `unit_type: 'account_id'` so multi-seat accounts see one consistent variant."
+      ].join("\n")
+    },
+    {
+      operationId: "updateUniverse",
+      method: "PATCH",
+      path: "/{id}",
+      summary: "Update a universe",
+      description: [
+        "Partial update. Only `holdout_range` is mutable \u2014 `name` and `unit_type` are immutable after create.",
+        "",
+        'Pass `"holdout_range": null` to remove an existing holdout.'
+      ].join("\n"),
+      pathParams: { id: "Stable opaque universe id (`uni_\u2026`)." },
+      request: universeUpdateSchema,
+      response: universeUpdateResponseSchema,
+      examples: {
+        requestExamples: {
+          setHoldout: {
+            summary: "Set holdout \u2014 reserve 5%",
+            description: "Reserve buckets 9500\u20139999 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 }
+          }
+        },
+        response: { id: "uni_01j7w8a1b2c3d4e5f6g7h8i9j0" }
+      },
+      useCase: [
+        "- **Adjust holdout** \u2014 change the reserved measurement slice without recreating experiments.",
+        '- **Remove holdout** \u2014 `{ "holdout_range": null }`.'
+      ].join("\n")
+    },
+    {
+      operationId: "deleteUniverse",
+      method: "DELETE",
+      path: "/{id}",
+      summary: "Delete a universe",
+      description: "Soft-deletes the universe. Returns `409` if any non-archived experiment still references it \u2014 archive those experiments first.",
+      pathParams: { id: "Stable opaque universe id." },
+      response: universeDeleteResponseSchema,
+      examples: { response: { ok: true } },
+      useCase: "Tear down a universe after every experiment that used it has been archived."
+    }
+  ]
+};
+export {
+  universesClient,
+  universesResource
+};

package/dist/transport.d.ts

@@ -0,0 +1,30 @@
+declare class ApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface Transport {
+    request<T>(method: HttpMethod, path: string, body?: unknown, query?: Record<string, string>): Promise<T>;
+}
+type HttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+interface AuthSnapshot {
+    token: string;
+    projectId: string;
+}
+interface HttpTransportOptions {
+    /** Base URL for the admin API, e.g. "https://shipeasy.ai" (no trailing slash required). */
+    baseUrl: string;
+    /**
+     * Returns the auth token + project_id for the next request. Called per request
+     * so consumers can refresh credentials or apply per-call project overrides.
+     */
+    getAuth(): AuthSnapshot;
+    /**
+     * Optional gate run before any non-GET request. Throw to abort. CLI uses this
+     * to enforce `.shipeasy` binding for mutations; MCP uses it to surface a
+     * notBound error. GET requests bypass this hook.
+     */
+    beforeMutation?(method: HttpMethod, path: string): void | Promise<void>;
+}
+declare function createHttpTransport(opts: HttpTransportOptions): Transport;
+
+export { ApiError, type AuthSnapshot, type HttpMethod, type HttpTransportOptions, type Transport, createHttpTransport };

package/dist/transport.js

@@ -0,0 +1,44 @@
+// src/transport.ts
+var ApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+  }
+  status;
+};
+function createHttpTransport(opts) {
+  const baseUrl = opts.baseUrl.replace(/\/$/, "");
+  return {
+    async request(method, path, body, query) {
+      if (method !== "GET" && opts.beforeMutation) {
+        await opts.beforeMutation(method, path);
+      }
+      const auth = opts.getAuth();
+      const url = new URL(`${baseUrl}${path}`);
+      if (query) {
+        for (const [k, v] of Object.entries(query)) url.searchParams.set(k, v);
+      }
+      const res = await fetch(url.toString(), {
+        method,
+        headers: {
+          "X-SDK-Key": auth.token,
+          "X-Project-Id": auth.projectId,
+          "Content-Type": "application/json"
+        },
+        ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+      });
+      if (res.status === 204 || res.status === 202) return void 0;
+      const json = await res.json().catch(() => ({ error: `HTTP ${res.status}` }));
+      if (!res.ok) {
+        const msg = json.error ?? `HTTP ${res.status}`;
+        throw new ApiError(msg, res.status);
+      }
+      return json;
+    }
+  };
+}
+export {
+  ApiError,
+  createHttpTransport
+};