@sylphx/contract 0.2.0

package/dist/endpoints/environments.js

@@ -0,0 +1,237 @@
+/**
+ * Environments endpoints — mounted at two places in production:
+ *
+ *   • `/environments/*`           (standalone env ops — get, update, reveal
+ *                                  secret, regenerate webhook secret, keys)
+ *   • `/projects/:id/environments` (project-scoped list / create / provision)
+ *
+ * Response shapes mirror `apps/api/src/server/platform/routes/environments.ts`
+ * + `routes/management/projects/environments-crud.ts` (ADR-084 Wave 2b).
+ */
+import { Schema } from 'effect';
+import { defineEndpoint } from '../endpoint.js';
+import { CreateEnvironmentResult, DeleteOAuthProviderResult, Environment, EnvironmentKeys, EnvironmentLogsResult, ListEnvironmentsByProjectSlugResult, ListOAuthProvidersResult, PromoteEnvironmentInput, PromoteResult, ProvisionEnvironmentResult, RegenerateWebhookSecretResult, RevealSecretKeyResult, UpdateEnvironmentInput, UpsertOAuthProviderInput, UpsertOAuthProviderResult, } from '../schemas/environment.js';
+const ProjectIdPath = Schema.Struct({ id: Schema.String });
+/**
+ * Standalone env ops historically used `:id` in `management` SDK callsites.
+ * Production uses `:envId`. Keep `:id` in the contract path to preserve the
+ * SDK's interpolatePath callsites; the API-side wiring maps this to the
+ * `envId` param name when routes are migrated in Wave 2c.
+ */
+const EnvironmentIdPath = Schema.Struct({ id: Schema.String });
+const ProjectEnvPath = Schema.Struct({ id: Schema.String, envId: Schema.String });
+const PromotePath = Schema.Struct({ id: Schema.String, envId: Schema.String });
+const ListEnvironmentsQuery = Schema.Struct({ projectId: Schema.optional(Schema.String) });
+const ListEnvironmentsResponse = Schema.Struct({
+    object: Schema.optional(Schema.Literal('list')),
+    environments: Schema.optional(Schema.Array(Environment)),
+    data: Schema.optional(Schema.Array(Environment)),
+});
+const CreateEnvironmentBody = Schema.Struct({
+    projectId: Schema.optional(Schema.String),
+    envType: Schema.Literal('development', 'staging', 'production', 'preview'),
+    name: Schema.String,
+    branchPattern: Schema.optional(Schema.String),
+    autoDeploy: Schema.optional(Schema.Boolean),
+    approvalRequired: Schema.optional(Schema.Boolean),
+    ephemeral: Schema.optional(Schema.Boolean),
+    ttl: Schema.optional(Schema.String),
+});
+const RevealSecretBody = Schema.Struct({
+    confirmation: Schema.optional(Schema.String),
+});
+const ProvisionBody = Schema.Struct({ force: Schema.optional(Schema.Boolean) });
+export const environmentsEndpoints = {
+    // ── Project-scoped (under /projects/:id/environments) ─────────────
+    list: defineEndpoint({
+        method: 'GET',
+        path: '/projects/:id/environments',
+        params: ProjectIdPath,
+        response: Schema.Struct({
+            object: Schema.Literal('list'),
+            data: Schema.Array(Environment),
+        }),
+        summary: 'List environments for a project',
+        tags: ['environments'],
+    }),
+    create: defineEndpoint({
+        method: 'POST',
+        path: '/projects/:id/environments',
+        params: ProjectIdPath,
+        body: CreateEnvironmentBody,
+        response: CreateEnvironmentResult,
+        summary: 'Create a new environment for a project (returns raw secret key once)',
+        tags: ['environments'],
+    }),
+    getInProject: defineEndpoint({
+        method: 'GET',
+        path: '/projects/:id/environments/:envId',
+        params: ProjectEnvPath,
+        response: Environment,
+        summary: 'Get an environment by id (embeds live deploy status when available)',
+        tags: ['environments'],
+    }),
+    updateInProject: defineEndpoint({
+        method: 'PATCH',
+        path: '/projects/:id/environments/:envId',
+        params: ProjectEnvPath,
+        body: UpdateEnvironmentInput,
+        response: Environment,
+        summary: 'Update environment settings (triggers reconcile when networking/runtime change)',
+        tags: ['environments'],
+    }),
+    provision: defineEndpoint({
+        method: 'POST',
+        path: '/projects/:id/environments/:envId/provision',
+        params: ProjectEnvPath,
+        body: ProvisionBody,
+        response: ProvisionEnvironmentResult,
+        summary: 'Idempotent provision / force-reconcile of an environment',
+        tags: ['environments'],
+    }),
+    promote: defineEndpoint({
+        method: 'POST',
+        path: '/projects/:id/environments/:envId/promote',
+        params: PromotePath,
+        body: PromoteEnvironmentInput,
+        response: PromoteResult,
+        summary: 'Promote services from a source environment to the target',
+        tags: ['environments'],
+    }),
+    // ── Standalone (under /environments) ──────────────────────────────
+    listStandalone: defineEndpoint({
+        method: 'GET',
+        path: '/environments',
+        query: ListEnvironmentsQuery,
+        response: ListEnvironmentsResponse,
+        summary: 'List environments (standalone — filter by projectId)',
+        tags: ['environments'],
+    }),
+    createStandalone: defineEndpoint({
+        method: 'POST',
+        path: '/environments',
+        body: Schema.Struct({
+            projectId: Schema.String,
+            envType: Schema.Literal('development', 'staging', 'production', 'preview'),
+            name: Schema.String,
+            branchPattern: Schema.optional(Schema.String),
+            autoDeploy: Schema.optional(Schema.Boolean),
+            approvalRequired: Schema.optional(Schema.Boolean),
+            ephemeral: Schema.optional(Schema.Boolean),
+            ttl: Schema.optional(Schema.String),
+        }),
+        response: CreateEnvironmentResult,
+        summary: 'Create environment (standalone — projectId in body, super-admin only)',
+        tags: ['environments'],
+    }),
+    get: defineEndpoint({
+        method: 'GET',
+        path: '/environments/:envId',
+        params: EnvironmentIdPath,
+        response: Environment,
+        summary: 'Get an environment by id (standalone)',
+        tags: ['environments'],
+    }),
+    update: defineEndpoint({
+        method: 'PATCH',
+        path: '/environments/:envId',
+        params: EnvironmentIdPath,
+        body: UpdateEnvironmentInput,
+        response: Environment,
+        summary: 'Update environment (standalone mount)',
+        tags: ['environments'],
+    }),
+    delete: defineEndpoint({
+        method: 'DELETE',
+        path: '/environments/:envId',
+        params: EnvironmentIdPath,
+        response: Schema.Struct({
+            success: Schema.Boolean,
+            lifecycle: Schema.optional(Schema.String),
+        }),
+        summary: 'Delete an environment (transitions to lifecycle=terminating)',
+        tags: ['environments'],
+    }),
+    revealSecret: defineEndpoint({
+        method: 'POST',
+        path: '/environments/:envId/reveal-secret',
+        params: EnvironmentIdPath,
+        body: RevealSecretBody,
+        response: RevealSecretKeyResult,
+        summary: 'Audit-logged reveal of the secret key prefix (ADR-055 — raw key never stored)',
+        tags: ['environments'],
+    }),
+    regenerateWebhookSecret: defineEndpoint({
+        method: 'POST',
+        path: '/environments/:envId/regenerate-webhook-secret',
+        params: EnvironmentIdPath,
+        response: RegenerateWebhookSecretResult,
+        summary: 'Regenerate the env webhook signing secret (one-time visibility)',
+        tags: ['environments'],
+    }),
+    getKeys: defineEndpoint({
+        method: 'GET',
+        path: '/environments/:envId/keys',
+        params: EnvironmentIdPath,
+        response: EnvironmentKeys,
+        summary: 'Get key metadata (super-admin, prefixes only)',
+        tags: ['environments'],
+    }),
+    listByProjectSlug: defineEndpoint({
+        method: 'GET',
+        path: '/environments/projects/:id',
+        params: ProjectIdPath,
+        response: ListEnvironmentsByProjectSlugResult,
+        summary: 'List environments by project id or slug (Console — masked key prefixes + project metadata)',
+        tags: ['environments'],
+    }),
+    // ── BYOK OAuth providers (env-scoped) — ADR-084 Wave 3E ───────────────────
+    listOAuthProviders: defineEndpoint({
+        method: 'GET',
+        path: '/environments/:envId/oauth-providers',
+        params: EnvironmentIdPath,
+        response: ListOAuthProvidersResult,
+        summary: 'List BYOK OAuth provider configurations for an environment',
+        tags: ['environments'],
+    }),
+    upsertOAuthProvider: defineEndpoint({
+        method: 'PUT',
+        path: '/environments/:envId/oauth-providers/:provider',
+        params: Schema.Struct({
+            envId: Schema.String,
+            provider: Schema.String,
+        }),
+        body: UpsertOAuthProviderInput,
+        response: UpsertOAuthProviderResult,
+        summary: 'Upsert BYOK OAuth credentials for a provider (client secret encrypted at rest)',
+        tags: ['environments'],
+    }),
+    deleteOAuthProvider: defineEndpoint({
+        method: 'DELETE',
+        path: '/environments/:envId/oauth-providers/:provider',
+        params: Schema.Struct({
+            envId: Schema.String,
+            provider: Schema.String,
+        }),
+        response: DeleteOAuthProviderResult,
+        summary: 'Remove BYOK OAuth credentials for a provider',
+        tags: ['environments'],
+    }),
+    // ── Log stream (build + runtime, SSE-capable) — ADR-084 Wave 3E ──────────
+    logs: defineEndpoint({
+        method: 'GET',
+        path: '/environments/:envId/logs',
+        params: EnvironmentIdPath,
+        query: Schema.Struct({
+            type: Schema.optional(Schema.Literal('build', 'runtime')),
+            stream: Schema.optional(Schema.String),
+            deploymentId: Schema.optional(Schema.String),
+            since: Schema.optional(Schema.String),
+            level: Schema.optional(Schema.String),
+            limit: Schema.optional(Schema.String),
+        }),
+        response: EnvironmentLogsResult,
+        summary: 'Stream or tail environment logs (build or runtime). SSE when stream=true, JSON list otherwise.',
+        tags: ['environments'],
+    }),
+};