@sylphx/contract 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# @sylphx/contract
+
+## 0.2.0
+
+### Minor Changes
+
+- [`c4471cf`](https://github.com/SylphxAI/platform/commit/c4471cf729a2a60865d0df5bbf04b87f55d57858) Thanks [@shtse8](https://github.com/shtse8)! - Initial public release. Effect Schema SSOT for every Sylphx Platform API endpoint across the Management plane (`api.sylphx.com/v1`) and BaaS plane (`runtime.sylphx.com/v1`). Framework-free, Standard Schema-compatible. Both `@sylphx/management` and `@sylphx/sdk` derive their request / response / error types from this package — see ADR-084.
+
+## 0.1.0 (wrongly labelled 1.0.0; reverted 2026-04-23 — still in beta)
+
+### Changes
+
+- **Initial beta release.** Effect Schema SSOT for the entire Sylphx API surface. Per [ADR-084](https://github.com/SylphxAI/platform/blob/main/docs/adr/ADR-084-effect-schema-contract.md), every endpoint, request body, response envelope, and error type is defined once in this package and consumed everywhere — `apps/api` Hono routes, the published SDKs (`@sylphx/management`, `@sylphx/sdk`), and the derived `openapi.json` spec. Hand-written parallel types are a bug (ADR-084 Rule 2).
+- **70 endpoint groups, 82 schema files, ~745 endpoint definitions** covering three planes:
+  - **Management** (`api.sylphx.com/v1`, Bearer `slx_*` / `sk_*`): `projects`, `deployments`, `environments`, `databases`, `envVars`, `domains`, `organizations`, `secrets`, `users`, `ciSettings`, `github`, `billingSettings`, `serviceTokens`, `serviceTokenRequests`, `runners`, `backups`, `webhooks`, `tasks`, `storage`, `storageAdmin`, `realtime`, `realtimeAdmin`, `saml`, `oidc`, `security`, `monitoring`, `monitoringAdmin`, `analytics`, `analyticsAdmin`, `flags`, `flagsAdmin`, `experiments`, `newsletter`, `referralsAdmin`, `engagementAdmin`, `aiAdmin`, `search`, `sessionReplay`, `email`, `emailAdmin`, `notifications`, `notificationsAdmin`, `consentAdmin`, `privacy`, `plans`, `billingConsole`.
+  - **BaaS** (`<tenant-slug>.api.sylphx.com/v1`, ADR-083.1): `auth`, `refresh`, `challenge`, `kv`, `kvAdmin`, `email` (transactional send), `notifications` (push / in-app), `flags.evaluate`, `realtime` (pub/sub), `storage`, `search`.
+  - **Admin** (operator-only Console routes): `adminAiPlayground`, `adminAnomalies`, `adminApm`, `adminAudit`, `adminBilling`, `adminBroadcasts`, `adminConfig`, `adminConsent`, `adminImpersonation`, `adminInvitations`, `adminJwtKeys`, `adminLogs`, `adminPlans`, `adminProjects`, `adminProjectUsers`, `adminQuotas`, `adminTasks`, `adminTraces`, `adminUsers`.
+- **`defineEndpoint()` primitive.** Each endpoint carries `method`, `path`, `params`, `query`, `body`, `response`, `summary`, `tags`, `plane`, and optional `agentHint`. `plane` gates SDK generation and OpenAPI splitting. `agentHint` surfaces as `x-agent-hint` in the spec for LLM tool-callers.
+- **Standard Schema v1 compatible** via `Schema.standardSchemaV1(...)` — consumers that speak Standard Schema (hono-openapi, form libraries, agent SDKs) integrate without a plugin.
+- **Branded entity IDs.** `ProjectId`, `EnvironmentId`, `DeploymentId`, `UserId`, `OrganizationId`, `SecretId`, `DomainId`, etc. are branded strings — mixing IDs across entities is a type error.
+- **Tagged `ApiError` union.** `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitedError`, `InternalError` — consumers discriminate on `_tag` rather than parsing messages.
+- **JSON Schema derivation.** Every Effect Schema is emittable to JSON Schema via `JSONSchema.make(...)`, which is how `scripts/generate-openapi.ts` produces the OpenAPI 3.1 spec.
+- **Framework-free.** No Hono, Next.js, or runtime dependencies. Effect is a peer dependency (`>=3.21.0`); consumers bring their own version.
+- **ESM-only.** `"type": "module"`, `sideEffects: false`, Node ≥ 20. Per-entity (`./schemas/project`) and per-namespace (`./endpoints/projects`) subpath exports for tree-shaking.
+
+### Plane discipline (ADR-083)
+
+A single SSOT enforces the `401 plane_mismatch` rules identically on both clients — the contract is the canonical definition of which endpoints live on which plane.
+
+### Design rules (frozen for 0.x beta)
+
+1. Effect Schema only — no Zod, no manual TS interfaces, no OpenAPI hand-editing.
+2. Standard Schema compliant.
+3. Framework-free.
+4. Branded IDs.
+5. Tagged errors.
+6. Plane-aware (`management` | `baas` | `admin`).
+7. Agent-hint-aware (OpenAPI 4 forward-compat).
+
+---
+
+## Pre-release history
+
+`@sylphx/contract` was introduced mid-2026 as the replacement for the auto-generated type pipeline in `@sylphx/api-types`. The 0.1.0 beta above is the first publicly surfaced version; pre-release iteration happened on internal versions and culminated in the ADR-084 Wave 4 migration (2026-04-23) which dropped `@hono/zod-openapi` from `apps/api` and relocated the legacy Zod schema machinery.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sylphx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @sylphx/contract
+
+[![npm version](https://img.shields.io/npm/v/@sylphx/contract.svg)](https://www.npmjs.com/package/@sylphx/contract)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+> The Effect Schema SSOT for every Sylphx API endpoint.
+
+Part of [ADR-084 — Effect Schema Contract](https://github.com/SylphxAI/platform/blob/main/docs/adr/ADR-084-effect-schema-contract.md).
+
+## Installation
+
+```bash
+bun add @sylphx/contract effect
+# or
+npm install @sylphx/contract effect
+# or
+pnpm add @sylphx/contract effect
+```
+
+`effect` is a peer dependency — consumers bring their own version.
+
+## Why this exists
+
+One contract drives four consumers:
+
+```
+                    @sylphx/contract
+                 (Effect Schema + endpoint tuples)
+                            │
+         ┌──────────────┬───┴────────────┐
+         ▼              ▼                ▼
+     apps/api     @sylphx/management  @sylphx/sdk
+   (Hono routes)    (Management SDK)  (BaaS SDK)
+         │
+         ▼
+  scripts/generate-openapi.ts
+         │
+         ▼
+  openapi.json (derivation)
+```
+
+- **Hono routes** in `apps/api` wire each endpoint tuple through `hono-openapi` (Standard Schema adapter).
+- **Published SDKs** (`@sylphx/management`, `@sylphx/sdk`) derive their typed request/response signatures here — no hand-written duplicates (ADR-084 Rule 2). Effect types are stripped from the `.d.ts` at publish time so external consumers see a clean `Promise<T>` surface.
+- **OpenAPI 3.1 spec** is a derivation via `scripts/generate-openapi.ts`, not the source. Advanced cross-language consumers (Python, Go, Rust) get codegen output from the spec.
+
+## Quick start
+
+```ts
+import { Project, endpoints } from '@sylphx/contract'
+import { Schema } from 'effect'
+
+// Decode an API payload using Effect Schema directly.
+const project = Schema.decodeUnknownSync(Project)(payload)
+
+// Inspect endpoint metadata (method, path, request / response schemas).
+endpoints.projects.list.method    // 'GET'
+endpoints.projects.list.path      // '/projects'
+endpoints.projects.list.plane     // 'management'
+endpoints.projects.list.response  // Schema.Struct({ data: Schema.Array(Project) })
+
+// Bridge to any Standard Schema v1 consumer (hono-openapi, MCP SDK, …).
+const standardProject = Schema.standardSchemaV1(Project)
+const result = standardProject['~standard'].validate(payload)
+//             ^ { value: Project } | { issues: [...] }
+```
+
+## Design rules
+
+1. **Effect Schema only.** No Zod, no manual TS interfaces, no OpenAPI hand-editing.
+2. **Standard Schema compliant.** Every schema value exposes `~standard` via `Schema.standardSchemaV1(...)` — validator-library swap is free if the bet ever needs unwinding.
+3. **Framework-free.** No Hono, Next.js, or runtime dependencies. Consumers decide how to wire.
+4. **Branded IDs.** Entity IDs (`ProjectId`, `EnvironmentId`, …) are branded strings; mixing across entities is a type error.
+5. **Tagged errors.** Failures use discriminated unions on `_tag` — consumers pattern-match, never string-compare.
+6. **Plane-aware.** Each endpoint carries a `plane: 'management' | 'baas' | 'admin'` hint so the OpenAPI splitter and SDK generator scope correctly.
+7. **Agent-hint-aware.** Each endpoint may carry `agentHint: string` — emitted as `x-agent-hint` in the OpenAPI derivation for downstream LLM tool-callers.
+
+## Structure
+
+```
+src/
+  endpoint.ts          — defineEndpoint() + Endpoint<...> type
+  errors.ts            — ApiError tagged union (400/401/403/404/409/422/429/500)
+  index.ts             — barrel + flat `endpoints` map
+  schemas/             — one file per entity type (82 files)
+  endpoints/           — one file per namespace (70 files)
+```
+
+## Coverage
+
+Today: **70 endpoint groups, 82 schema files, ~745 endpoint definitions** across three planes.
+
+### Management plane (`api.sylphx.com/v1`)
+
+Platform-owner ops consumed by Console, CLI, CI integrations, and service-token automation (Bearer `slx_*` user / `sk_*` service).
+
+`projects`, `deployments`, `environments`, `databases`, `envVars`, `domains`, `organizations`, `secrets`, `users`, `ciSettings`, `github`, `billingSettings`, `serviceTokens`, `serviceTokenRequests`, `runners`, `backups`, `webhooks`, `tasks`, `storage`, `storageAdmin`, `realtime`, `realtimeAdmin`, `saml`, `oidc`, `security`, `monitoring`, `monitoringAdmin`, `analytics`, `analyticsAdmin`, `flags`, `flagsAdmin`, `experiments`, `newsletter`, `referralsAdmin`, `engagementAdmin`, `aiAdmin`, `search`, `sessionReplay`, `email`, `emailAdmin`, `notifications`, `notificationsAdmin`, `consentAdmin`, `privacy`, `plans`, `billingConsole`.
+
+### BaaS plane (`<tenant-slug>.api.sylphx.com/v1`, ADR-083.1)
+
+Runtime data-plane verbs consumed by deployed applications (`sk_*` + end-user JWT or `pk_*` + RLS).
+
+`auth`, `refresh`, `challenge`, `kv`, `kvAdmin`, `email` (transactional send), `notifications` (push / in-app), `flags.evaluate`, `realtime` (pub/sub), `storage`, `search`.
+
+### Admin plane
+
+Operator-only Console routes that customers never consume.
+
+`adminAiPlayground`, `adminAnomalies`, `adminApm`, `adminAudit`, `adminBilling`, `adminBroadcasts`, `adminConfig`, `adminConsent`, `adminImpersonation`, `adminInvitations`, `adminJwtKeys`, `adminLogs`, `adminPlans`, `adminProjects`, `adminProjectUsers`, `adminQuotas`, `adminTasks`, `adminTraces`, `adminUsers`.
+
+## Defining a new endpoint
+
+```ts
+// packages/contract/src/endpoints/tasks.ts
+import { Schema } from 'effect'
+import { defineEndpoint } from '../endpoint.js'
+import { Task, TaskId } from '../schemas/task.js'
+
+export const tasksEndpoints = {
+  list: defineEndpoint({
+    method: 'GET',
+    path: '/tasks',
+    response: Schema.Struct({ data: Schema.Array(Task) }),
+    summary: 'List tasks across the current org.',
+    tags: ['tasks'],
+    plane: 'management',
+    agentHint: 'Call this before triggering a new run to avoid duplicate work.',
+  }),
+  create: defineEndpoint({
+    method: 'POST',
+    path: '/tasks',
+    body: Schema.Struct({ name: Schema.String }),
+    response: Task,
+    plane: 'management',
+  }),
+  get: defineEndpoint({
+    method: 'GET',
+    path: '/tasks/:id',
+    params: Schema.Struct({ id: TaskId }),
+    response: Task,
+    plane: 'management',
+  }),
+} as const
+```
+
+Register the group in `src/index.ts` and every downstream consumer (API, both SDKs, OpenAPI spec) picks it up. CI (`scripts/check-contract-first.ts`) rejects net-new `@hono/zod-openapi` routes and hand-written SDK types.
+
+## Subpath imports
+
+Tree-shake a single entity schema or endpoint group without pulling the entire barrel:
+
+```ts
+import { Project, ProjectId } from '@sylphx/contract/schemas/project'
+import { projectsEndpoints } from '@sylphx/contract/endpoints/projects'
+```
+
+## Related packages
+
+- [`@sylphx/management`](https://www.npmjs.com/package/@sylphx/management) — Promise client for the Management plane, types derived from this contract.
+- [`@sylphx/sdk`](https://www.npmjs.com/package/@sylphx/sdk) — runtime BaaS SDK for deployed apps.
+- [`@sylphx/cli`](https://www.npmjs.com/package/@sylphx/cli) — interactive CLI built on `@sylphx/management`.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/endpoint.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Endpoint tuple primitive — framework-free description of an HTTP operation.
+ *
+ * Consumers:
+ *   - `apps/api` wires each endpoint to a Hono handler via `hono-openapi`
+ *     (Standard Schema adapter).
+ *   - `@sylphx/management` + `@sylphx/sdk` derive their typed request/response
+ *     signatures directly from these tuples — no hand-written types allowed
+ *     (ADR-084 Rule 2).
+ *
+ * Schemas carried here are Effect `Schema.Schema<A, I, R>` values. Effect
+ * Schema implements Standard Schema's `~standard` interface natively, so
+ * every consumer that speaks Standard Schema works without adapters.
+ */
+import type { Schema } from 'effect';
+/** HTTP method whitelist — what Hono understands. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Structural endpoint definition. Each schema is optional independently so
+ * GETs can skip `body`, DELETEs can skip `body` + `query`, etc.
+ *
+ * `ResponseSchema` is the default/success envelope. Errors are carried as a
+ * record keyed by HTTP status code → Effect Schema, so the generated
+ * OpenAPI derivation and the SDK strip-at-publish both see the full failure
+ * surface (ADR-084 §1).
+ */
+export interface Endpoint<Method extends HttpMethod = HttpMethod, Path extends string = string, Params extends Schema.Schema<any, any, never> | undefined = any, Query extends Schema.Schema<any, any, never> | undefined = any, Body extends Schema.Schema<any, any, never> | undefined = any, Response extends Schema.Schema<any, any, never> = Schema.Schema<any, any, never>> {
+    readonly method: Method;
+    readonly path: Path;
+    readonly params?: Params;
+    readonly query?: Query;
+    readonly body?: Body;
+    readonly response: Response;
+    readonly errors?: Readonly<Record<number, Schema.Schema.AnyNoContext>>;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    /**
+     * Control-plane vs data-plane routing hint. Consumed by
+     *   • `scripts/generate-openapi.ts` → emitted as `x-sylphx-plane`
+     *   • SDK/management splitter → decides whether the endpoint hangs off
+     *     `api.sylphx.com` (management) or `<tenant-slug>.api.sylphx.com`
+     *     (baas, per ADR-083.1).
+     *
+     * `admin` is a distinct plane covering Console operator-dashboard routes
+     * that customers never consume (super-admin platform administration).
+     */
+    readonly plane?: 'management' | 'baas' | 'admin';
+    /** LLM-targeted description emitted as `x-agent-hint` (OpenAPI 4 forward-compat). */
+    readonly agentHint?: string;
+}
+/**
+ * Identity helper that preserves the full literal shape of every field.
+ * Calling `defineEndpoint({...})` instead of an object literal lets
+ * TypeScript capture the exact `method`, `path`, and schema identities —
+ * which downstream consumers (SDK codegen, MCP tool descriptors, Hono route
+ * builder) rely on for type-level path-parameter inference.
+ */
+export declare const defineEndpoint: <Method extends HttpMethod, Path extends string, Params extends Schema.Schema.AnyNoContext | undefined, Query extends Schema.Schema.AnyNoContext | undefined, Body extends Schema.Schema.AnyNoContext | undefined, Response extends Schema.Schema.AnyNoContext>(endpoint: Endpoint<Method, Path, Params, Query, Body, Response>) => Endpoint<Method, Path, Params, Query, Body, Response>;
+/**
+ * A record of endpoints grouped by a capability namespace — e.g. the object
+ * exported from `endpoints/projects.ts`.
+ */
+export type EndpointGroup = Readonly<Record<string, Endpoint>>;
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../src/endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC,qDAAqD;AACrD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEpE;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ,CACxB,MAAM,SAAS,UAAU,GAAG,UAAU,EACtC,IAAI,SAAS,MAAM,GAAG,MAAM,EAE5B,MAAM,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,SAAS,GAAG,GAAG,EAE/D,KAAK,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,SAAS,GAAG,GAAG,EAE9D,IAAI,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,SAAS,GAAG,GAAG,EAE7D,QAAQ,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC;IAEhF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAA;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,MAAM,GAAG,OAAO,CAAA;IAChD,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAC1B,MAAM,SAAS,UAAU,EACzB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,CAAC,MAAM,CAAC,YAAY,GAAG,SAAS,EACrD,KAAK,SAAS,MAAM,CAAC,MAAM,CAAC,YAAY,GAAG,SAAS,EACpD,IAAI,SAAS,MAAM,CAAC,MAAM,CAAC,YAAY,GAAG,SAAS,EACnD,QAAQ,SAAS,MAAM,CAAC,MAAM,CAAC,YAAY,EAE3C,UAAU,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,KAC7D,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAa,CAAA;AAEpE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA"}

package/dist/endpoint.js

@@ -0,0 +1,22 @@
+/**
+ * Endpoint tuple primitive — framework-free description of an HTTP operation.
+ *
+ * Consumers:
+ *   - `apps/api` wires each endpoint to a Hono handler via `hono-openapi`
+ *     (Standard Schema adapter).
+ *   - `@sylphx/management` + `@sylphx/sdk` derive their typed request/response
+ *     signatures directly from these tuples — no hand-written types allowed
+ *     (ADR-084 Rule 2).
+ *
+ * Schemas carried here are Effect `Schema.Schema<A, I, R>` values. Effect
+ * Schema implements Standard Schema's `~standard` interface natively, so
+ * every consumer that speaks Standard Schema works without adapters.
+ */
+/**
+ * Identity helper that preserves the full literal shape of every field.
+ * Calling `defineEndpoint({...})` instead of an object literal lets
+ * TypeScript capture the exact `method`, `path`, and schema identities —
+ * which downstream consumers (SDK codegen, MCP tool descriptors, Hono route
+ * builder) rely on for type-level path-parameter inference.
+ */
+export const defineEndpoint = (endpoint) => endpoint;

package/dist/endpoints/admin-ai-playground.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Admin AI Playground endpoints — Console operator dashboard AI model testing.
+ * Mirrors `apps/api/src/server/platform/routes/admin/ai-playground.ts`.
+ *
+ * Production mount: `/admin/ai-playground/*`. The `/stream` SSE endpoint is
+ * handler-side only — it emits `text/event-stream`, not JSON.
+ */
+export declare const adminAiPlaygroundEndpoints: {
+    readonly listModels: import("../endpoint.js").Endpoint<"GET", "/admin/ai-playground/models", import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        models: import("effect/Schema").Array$<import("effect/Schema").Struct<{
+            id: typeof import("effect/Schema").String;
+            name: typeof import("effect/Schema").String;
+            contextWindow: typeof import("effect/Schema").Number;
+            capabilities: import("effect/Schema").Struct<{
+                chat: typeof import("effect/Schema").Boolean;
+                completion: typeof import("effect/Schema").Boolean;
+                embedding: import("effect/Schema").optional<typeof import("effect/Schema").Boolean>;
+                vision: import("effect/Schema").optional<typeof import("effect/Schema").Boolean>;
+                functionCalling: import("effect/Schema").optional<typeof import("effect/Schema").Boolean>;
+            }>;
+            inputCostPer1M: typeof import("effect/Schema").Number;
+            outputCostPer1M: typeof import("effect/Schema").Number;
+        }>>;
+    }>>;
+    readonly chat: import("../endpoint.js").Endpoint<"POST", "/admin/ai-playground/chat", import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        projectId: typeof import("effect/Schema").String;
+        model: typeof import("effect/Schema").String;
+        messages: import("effect/Schema").Array$<import("effect/Schema").Struct<{
+            role: import("effect/Schema").Literal<["user", "assistant", "system"]>;
+            content: import("effect/Schema").Union<[typeof import("effect/Schema").String, import("effect/Schema").Array$<import("effect/Schema").Struct<{
+                type: import("effect/Schema").Literal<["text", "image"]>;
+                text: import("effect/Schema").optional<typeof import("effect/Schema").String>;
+                image: import("effect/Schema").optional<typeof import("effect/Schema").String>;
+            }>>]>;
+        }>>;
+        temperature: import("effect/Schema").optional<typeof import("effect/Schema").Number>;
+        maxTokens: import("effect/Schema").optional<typeof import("effect/Schema").Number>;
+        topP: import("effect/Schema").optional<typeof import("effect/Schema").Number>;
+        frequencyPenalty: import("effect/Schema").optional<typeof import("effect/Schema").Number>;
+        presencePenalty: import("effect/Schema").optional<typeof import("effect/Schema").Number>;
+        stop: import("effect/Schema").optional<import("effect/Schema").Union<[typeof import("effect/Schema").String, import("effect/Schema").Array$<typeof import("effect/Schema").String>]>>;
+        responseFormat: import("effect/Schema").optional<import("effect/Schema").Struct<{
+            type: import("effect/Schema").Literal<["text", "json_object"]>;
+        }>>;
+        tools: import("effect/Schema").optional<typeof import("effect/Schema").Unknown>;
+        toolChoice: import("effect/Schema").optional<import("effect/Schema").Literal<["auto", "none", "required"]>>;
+        stream: import("effect/Schema").optional<typeof import("effect/Schema").Boolean>;
+    }>, import("effect/Schema").Struct<{
+        id: typeof import("effect/Schema").String;
+        model: typeof import("effect/Schema").String;
+        content: typeof import("effect/Schema").String;
+        finishReason: typeof import("effect/Schema").String;
+        usage: import("effect/Schema").Struct<{
+            inputTokens: typeof import("effect/Schema").Number;
+            outputTokens: typeof import("effect/Schema").Number;
+            totalTokens: typeof import("effect/Schema").Number;
+        }>;
+        latencyMs: typeof import("effect/Schema").Number;
+        toolCalls: import("effect/Schema").optional<import("effect/Schema").Array$<import("effect/Schema").Struct<{
+            id: typeof import("effect/Schema").String;
+            name: typeof import("effect/Schema").String;
+            arguments: import("effect/Schema").Record$<typeof import("effect/Schema").String, typeof import("effect/Schema").Unknown>;
+        }>>>;
+    }>>;
+    readonly chatStream: import("../endpoint.js").Endpoint<"POST", "/admin/ai-playground/chat/stream", import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        projectId: typeof import("effect/Schema").String;
+        model: typeof import("effect/Schema").String;
+        messages: import("effect/Schema").Array$<import("effect/Schema").Struct<{
+            role: import("effect/Schema").Literal<["user", "assistant", "system"]>;
+            content: import("effect/Schema").Union<[typeof import("effect/Schema").String, import("effect/Schema").Array$<import("effect/Schema").Struct<{
+                type: import("effect/Schema").Literal<["text", "image"]>;
+                text: import("effect/Schema").optional<typeof import("effect/Schema").String>;
+                image: import("effect/Schema").optional<typeof import("effect/Schema").String>;
+            }>>]>;
+        }>>;
+        temperature: import("effect/Schema").optional<typeof import("effect/Schema").Number>;
+        maxTokens: import("effect/Schema").optional<typeof import("effect/Schema").Number>;
+        topP: import("effect/Schema").optional<typeof import("effect/Schema").Number>;
+        frequencyPenalty: import("effect/Schema").optional<typeof import("effect/Schema").Number>;
+        presencePenalty: import("effect/Schema").optional<typeof import("effect/Schema").Number>;
+        stop: import("effect/Schema").optional<import("effect/Schema").Union<[typeof import("effect/Schema").String, import("effect/Schema").Array$<typeof import("effect/Schema").String>]>>;
+        responseFormat: import("effect/Schema").optional<import("effect/Schema").Struct<{
+            type: import("effect/Schema").Literal<["text", "json_object"]>;
+        }>>;
+        tools: import("effect/Schema").optional<typeof import("effect/Schema").Unknown>;
+        toolChoice: import("effect/Schema").optional<import("effect/Schema").Literal<["auto", "none", "required"]>>;
+        stream: import("effect/Schema").optional<typeof import("effect/Schema").Boolean>;
+    }>, import("effect/Schema").Struct<{
+        streamId: typeof import("effect/Schema").String;
+        projectId: typeof import("effect/Schema").String;
+    }>>;
+};
+//# sourceMappingURL=admin-ai-playground.d.ts.map

package/dist/endpoints/admin-ai-playground.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-ai-playground.d.ts","sourceRoot":"","sources":["../../src/endpoints/admin-ai-playground.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2B7B,CAAA"}

package/dist/endpoints/admin-ai-playground.js

@@ -0,0 +1,37 @@
+/**
+ * Admin AI Playground endpoints — Console operator dashboard AI model testing.
+ * Mirrors `apps/api/src/server/platform/routes/admin/ai-playground.ts`.
+ *
+ * Production mount: `/admin/ai-playground/*`. The `/stream` SSE endpoint is
+ * handler-side only — it emits `text/event-stream`, not JSON.
+ */
+import { defineEndpoint } from '../endpoint.js';
+import { AdminListModelsResult, AdminPlaygroundChatInput, AdminPlaygroundChatResult, AdminPlaygroundStreamResult, } from '../schemas/admin-ai-playground.js';
+export const adminAiPlaygroundEndpoints = {
+    listModels: defineEndpoint({
+        method: 'GET',
+        path: '/admin/ai-playground/models',
+        response: AdminListModelsResult,
+        plane: 'admin',
+        summary: 'List AI models available in the playground',
+        tags: ['admin-ai-playground'],
+    }),
+    chat: defineEndpoint({
+        method: 'POST',
+        path: '/admin/ai-playground/chat',
+        body: AdminPlaygroundChatInput,
+        response: AdminPlaygroundChatResult,
+        plane: 'admin',
+        summary: 'Non-streaming chat completion in playground',
+        tags: ['admin-ai-playground'],
+    }),
+    chatStream: defineEndpoint({
+        method: 'POST',
+        path: '/admin/ai-playground/chat/stream',
+        body: AdminPlaygroundChatInput,
+        response: AdminPlaygroundStreamResult,
+        plane: 'admin',
+        summary: 'Initialise a streaming chat completion (returns streamId)',
+        tags: ['admin-ai-playground'],
+    }),
+};

package/dist/endpoints/admin-anomalies.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Admin Anomalies endpoints — Console operator dashboard spending anomaly ops.
+ * Mirrors `apps/api/src/server/platform/routes/admin/anomalies.ts`.
+ *
+ * Production mount: `/admin/anomalies/*`.
+ */
+export declare const adminAnomaliesEndpoints: {
+    readonly stats: import("../endpoint.js").Endpoint<"GET", "/admin/anomalies/stats", import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        open: typeof import("effect/Schema").Number;
+        acknowledged: typeof import("effect/Schema").Number;
+        resolved: typeof import("effect/Schema").Number;
+        dismissed: typeof import("effect/Schema").Number;
+        total: typeof import("effect/Schema").Number;
+    }>>;
+    readonly list: import("../endpoint.js").Endpoint<"GET", "/admin/anomalies/", import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        page: import("effect/Schema").optional<typeof import("effect/Schema").String>;
+        limit: import("effect/Schema").optional<typeof import("effect/Schema").String>;
+        status: import("effect/Schema").optional<import("effect/Schema").Literal<["all", "open", "acknowledged", "resolved", "dismissed"]>>;
+        type: import("effect/Schema").optional<import("effect/Schema").Literal<["all", "spike", "unusual_service", "unusual_time", "threshold_breach"]>>;
+        dateFrom: import("effect/Schema").optional<typeof import("effect/Schema").String>;
+        dateTo: import("effect/Schema").optional<typeof import("effect/Schema").String>;
+    }>, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        anomalies: import("effect/Schema").Array$<import("effect/Schema").Struct<{
+            id: typeof import("effect/Schema").String;
+            anomalyType: import("effect/Schema").Literal<["spike", "unusual_service", "unusual_time", "threshold_breach"]>;
+            service: import("effect/Schema").NullOr<typeof import("effect/Schema").String>;
+            detectedValueDollars: typeof import("effect/Schema").Number;
+            expectedValueDollars: typeof import("effect/Schema").Number;
+            deviationPercent: typeof import("effect/Schema").Number;
+            description: typeof import("effect/Schema").String;
+            status: import("effect/Schema").Literal<["open", "acknowledged", "resolved", "dismissed"]>;
+            resolvedAt: import("effect/Schema").NullOr<typeof import("effect/Schema").String>;
+            resolvedBy: import("effect/Schema").NullOr<typeof import("effect/Schema").String>;
+            resolutionNotes: import("effect/Schema").NullOr<typeof import("effect/Schema").String>;
+            createdAt: typeof import("effect/Schema").String;
+        }>>;
+        pagination: import("effect/Schema").Struct<{
+            page: typeof import("effect/Schema").Number;
+            limit: typeof import("effect/Schema").Number;
+            total: typeof import("effect/Schema").Number;
+            totalPages: typeof import("effect/Schema").Number;
+        }>;
+    }>>;
+    readonly get: import("../endpoint.js").Endpoint<"GET", "/admin/anomalies/:anomalyId", import("effect/Schema").Struct<{
+        anomalyId: typeof import("effect/Schema").String;
+    }>, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        id: typeof import("effect/Schema").String;
+        orgId: typeof import("effect/Schema").String;
+        anomalyType: import("effect/Schema").Literal<["spike", "unusual_service", "unusual_time", "threshold_breach"]>;
+        service: import("effect/Schema").NullOr<typeof import("effect/Schema").String>;
+        detectedValueDollars: typeof import("effect/Schema").Number;
+        expectedValueDollars: typeof import("effect/Schema").Number;
+        deviationPercent: typeof import("effect/Schema").Number;
+        description: typeof import("effect/Schema").String;
+        metadata: import("effect/Schema").NullOr<typeof import("effect/Schema").Unknown>;
+        status: import("effect/Schema").Literal<["open", "acknowledged", "resolved", "dismissed"]>;
+        resolvedAt: import("effect/Schema").NullOr<typeof import("effect/Schema").String>;
+        resolvedBy: import("effect/Schema").NullOr<typeof import("effect/Schema").String>;
+        resolutionNotes: import("effect/Schema").NullOr<typeof import("effect/Schema").String>;
+        createdAt: typeof import("effect/Schema").String;
+    }>>;
+    readonly acknowledge: import("../endpoint.js").Endpoint<"POST", "/admin/anomalies/:anomalyId/acknowledge", import("effect/Schema").Struct<{
+        anomalyId: typeof import("effect/Schema").String;
+    }>, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        success: typeof import("effect/Schema").Boolean;
+        status: import("effect/Schema").Literal<["open", "acknowledged", "resolved", "dismissed"]>;
+    }>>;
+    readonly dismiss: import("../endpoint.js").Endpoint<"POST", "/admin/anomalies/:anomalyId/dismiss", import("effect/Schema").Struct<{
+        anomalyId: typeof import("effect/Schema").String;
+    }>, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        success: typeof import("effect/Schema").Boolean;
+        status: import("effect/Schema").Literal<["open", "acknowledged", "resolved", "dismissed"]>;
+    }>>;
+    readonly resolve: import("../endpoint.js").Endpoint<"POST", "/admin/anomalies/:anomalyId/resolve", import("effect/Schema").Struct<{
+        anomalyId: typeof import("effect/Schema").String;
+    }>, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        notes: typeof import("effect/Schema").String;
+    }>, import("effect/Schema").Struct<{
+        success: typeof import("effect/Schema").Boolean;
+        status: import("effect/Schema").Literal<["open", "acknowledged", "resolved", "dismissed"]>;
+    }>>;
+    readonly errorsOverview: import("../endpoint.js").Endpoint<"GET", "/admin/anomalies/errors/overview", import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Schema.AnyNoContext | undefined, import("effect/Schema").Struct<{
+        total: typeof import("effect/Schema").Number;
+        unresolved: typeof import("effect/Schema").Number;
+        bySeverity: import("effect/Schema").Record$<typeof import("effect/Schema").String, typeof import("effect/Schema").Number>;
+        recentErrors: import("effect/Schema").Array$<import("effect/Schema").Struct<{
+            id: typeof import("effect/Schema").String;
+            errorType: typeof import("effect/Schema").String;
+            message: typeof import("effect/Schema").String;
+            severity: typeof import("effect/Schema").String;
+            count: typeof import("effect/Schema").Number;
+            resolved: typeof import("effect/Schema").Boolean;
+            lastSeen: typeof import("effect/Schema").String;
+            createdAt: typeof import("effect/Schema").String;
+            app: import("effect/Schema").NullOr<import("effect/Schema").Struct<{
+                id: typeof import("effect/Schema").String;
+                name: typeof import("effect/Schema").String;
+                slug: typeof import("effect/Schema").String;
+            }>>;
+        }>>;
+        byProject: import("effect/Schema").Array$<import("effect/Schema").Struct<{
+            projectId: typeof import("effect/Schema").String;
+            projectName: import("effect/Schema").NullOr<typeof import("effect/Schema").String>;
+            count: typeof import("effect/Schema").Number;
+        }>>;
+    }>>;
+};
+//# sourceMappingURL=admin-anomalies.d.ts.map

package/dist/endpoints/admin-anomalies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-anomalies.d.ts","sourceRoot":"","sources":["../../src/endpoints/admin-anomalies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+D1B,CAAA"}