@xemahq/biome-sdk 0.1.1

package/src/api/lib/api-manifest.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+
+/**
+ * Closed-set scope flag on a biome API endpoint. Mirrors the storage
+ * scope concept — every endpoint declares the authorization context
+ * its handler needs, so the ingress shim can inject the matching
+ * `X-Org-Id` / `X-Project-Id` / `X-Installation-Id` headers from the
+ * platform JWT without the biome doing claim parsing.
+ */
+export enum BiomeApiScope {
+  Public = 'public',
+  Org = 'org',
+  Project = 'project',
+  Installation = 'installation',
+}
+
+/**
+ * Per-API declaration. Biomes ship one of these per logical API
+ * surface under `xema.ships.apis[]`. `name` becomes the subdomain
+ * slug — final URL is `<name>.api.<base-domain>` (e.g. `linear.api.xema.dev`).
+ * `basePath` is the in-process route prefix (defaults to `/`).
+ *
+ * Biome-host-api reads these at install time and writes one route-
+ * registry entry per API to the Redis store the ingress consults
+ * (same primitive the output surface gateway already runs — see
+ * `.claude/plans/golden-floating-piglet.md`).
+ */
+export const BiomeApiManifestEntrySchema = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .regex(
+        /^[a-z][a-z0-9-]*$/,
+        'API name must be lowercase kebab-case; becomes the subdomain slug',
+      ),
+    basePath: z.string().regex(/^\/.*$/).default('/'),
+    /** Workspace package the API deployment image is built from. */
+    image: z.object({
+      package: z.string().min(1),
+      port: z.number().int().min(1).max(65_535),
+    }),
+    /**
+     * OpenAPI spec path inside the biome package. Biome-host-api
+     * fetches it at install time + warns if the manifest's declared
+     * surface (auth scope, scopes used) doesn't match the spec.
+     */
+    openapiSpec: z.string().optional(),
+    scopes: z.array(z.nativeEnum(BiomeApiScope)).min(1),
+  })
+  .strict();
+export type BiomeApiManifestEntry = z.infer<typeof BiomeApiManifestEntrySchema>;
+
+export const BiomeApiManifestSchema = z.array(BiomeApiManifestEntrySchema);

package/src/api/lib/biome-db.ts

@@ -0,0 +1,28 @@
+/**
+ * Set Postgres `search_path` from Prisma's `?schema=` URL parameter.
+ *
+ * `@prisma/adapter-pg` (Prisma 7's driver-adapter) does NOT honour the
+ * `?schema=` URL parameter at runtime — `pg.Pool` ignores it. The
+ * parameter is only read by `prisma migrate` to target the right schema.
+ * Without explicit `search_path`, runtime queries fall back to
+ * Postgres's default (`public`), so biome services that store their
+ * tables in a per-biome schema (e.g. `biome_webapp_studio` inside
+ * the shared `xema_biomes` database) get
+ * `relation "public.<table>" does not exist`.
+ *
+ * `libpq`'s `options=-c search_path=...` URL param is the canonical
+ * fix; `pg` forwards it in the PostgreSQL startup packet so every new
+ * connection in the pool has the right `search_path` set.
+ *
+ * Call this once in `PrismaService`'s constructor before passing the
+ * connection string to `PrismaPg`.
+ */
+export function ensureBiomeDbSearchPath(connectionString: string): string {
+  const url = new URL(connectionString);
+  const schema = url.searchParams.get('schema');
+  if (!schema || schema === 'public' || url.searchParams.has('options')) {
+    return connectionString;
+  }
+  url.searchParams.set('options', `-c search_path=${schema},public`);
+  return url.toString();
+}

package/src/api/lib/code-tool-context.ts

@@ -0,0 +1,45 @@
+import type { BiomeApiRequestContext } from './request-context';
+
+/**
+ * Runtime context handed to a `@BiomeCodeTool` handler. Extends the
+ * generic `BiomeApiRequestContext` with the platform-mediated
+ * sub-clients biomes use to reach storage, credentials, and
+ * outbound integrations — all scope-bound by the platform so biome
+ * code cannot cross-tenant leak by construction.
+ *
+ * Sub-clients are NOT bundled into this SDK — they live in the
+ * domain-specific SDKs (`@xemahq/biome-storage-sdk`,
+ * `@xemahq/biome-activity-sdk`, ...). The biome's handler factory
+ * composes them; this interface is the union of fields the handler
+ * is guaranteed to see.
+ */
+export interface CodeToolCtx extends BiomeApiRequestContext {
+  /** Mandatory in code-tool context (different from raw biome API). */
+  readonly projectId: string;
+  /** Mandatory in code-tool context. */
+  readonly installationId: string;
+  /** Session/allocation the invoking agent runs in (for audit + scope). */
+  readonly sessionId: string;
+  /** Per-call correlation id surfaced to logs + traces. */
+  readonly correlationId: string;
+  /**
+   * Sub-clients are NOT declared on the kernel interface — biome
+   * code receives them via DI in its handler class. The handler
+   * implementation decides which sub-clients it depends on.
+   */
+}
+
+/**
+ * Open-set lookup key for sub-clients. Biomes import these symbols
+ * from the relevant SDK; the platform's biome runner wires the
+ * matching client at handler resolution time. Closed-set enum kept
+ * deliberately small — sub-clients evolve independently.
+ */
+export const CODE_TOOL_CTX_KEYS = {
+  orgId: 'orgId',
+  projectId: 'projectId',
+  installationId: 'installationId',
+  sessionId: 'sessionId',
+  actorSubject: 'actorSubject',
+  correlationId: 'correlationId',
+} as const;

package/src/api/lib/code-tool-descriptor.ts

@@ -0,0 +1,102 @@
+/**
+ * Wire-format descriptor a biome API exposes via
+ * `GET /code-tools-manifest`. The platform's
+ * `BiomeCodeToolsProvider` reads this list to project MCP tools for
+ * the installation. Pure types — no runtime dependency on NestJS
+ * (biome authors free to use any HTTP framework).
+ *
+ * The biome's API service ships its handlers under
+ * `POST /biome-code-tools/:key` (one route per tool). The platform
+ * resolver issues the invocation; biome code never sees MCP
+ * protocol bytes.
+ */
+
+import type { ToolProviderKind } from './provider-kind-mirror';
+
+/** Output kind hint the platform surfaces to the calling MCP agent. */
+export type BiomeCodeToolOutputKind = 'structured' | 'text' | 'artifact';
+
+export interface BiomeCodeToolMountHint {
+  readonly slot: 'inputs' | 'references' | 'deliverables';
+  readonly as: string;
+}
+
+export interface BiomeCodeToolDescriptor {
+  readonly key: string;
+  readonly displayName: string;
+  readonly description: string;
+  /**
+   * JSON Schema 2020-12 shape the platform exposes to the MCP agent as
+   * the tool's `inputSchema`. The biome SDK's decorator emits this
+   * automatically from a Zod schema; biomes not using Zod can supply
+   * raw JSON Schema directly.
+   */
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  /**
+   * Hint about the tool's primary output shape. `'structured'` returns
+   * a JSON object the agent reads inline; `'text'` returns a plain
+   * string; `'artifact'` emits an ArtifactRef the platform fetches +
+   * optionally mounts via workspace-proxy (see `mount`).
+   */
+  readonly outputKind: BiomeCodeToolOutputKind;
+  /**
+   * Optional workspace mount target — when present, the platform
+   * fetches the returned artifact bytes and applies them to the
+   * calling agent's workspace at `/workspace/<slot>/<as>` so the
+   * result appears as a regular file.
+   */
+  readonly mount?: BiomeCodeToolMountHint;
+}
+
+/** Body shape of `GET /code-tools-manifest`. */
+export interface BiomeCodeToolsManifestDto {
+  readonly tools: readonly BiomeCodeToolDescriptor[];
+}
+
+/**
+ * Body shape of `POST /biome-code-tools/:key`. The platform sends
+ * `{args, scope}` and a service token in `Authorization: Bearer`.
+ */
+export interface BiomeCodeToolInvocationDto {
+  readonly args: Readonly<Record<string, unknown>>;
+  readonly scope: {
+    readonly orgId: string;
+    readonly projectId: string;
+    readonly sessionId: string;
+    readonly actorSubject: string | null;
+    readonly installationId: string;
+  };
+}
+
+/** Response shape. Discriminated by `kind`. */
+export type BiomeCodeToolInvocationResult =
+  | {
+      readonly kind: 'structured';
+      readonly value: Readonly<Record<string, unknown>>;
+    }
+  | {
+      readonly kind: 'text';
+      readonly value: string;
+    }
+  | {
+      readonly kind: 'artifact';
+      readonly artifactRef: {
+        readonly artifactId: string;
+        readonly versionId: string;
+        readonly version: number;
+        readonly hash?: string;
+      };
+      readonly inlineSnippet?: string;
+    }
+  | {
+      readonly kind: 'error';
+      readonly message: string;
+      readonly retryable?: boolean;
+    };
+
+/**
+ * Re-export the mcp-tool-contracts `ToolProviderKind` value used in
+ * downstream registries. Kept here for biomes that want to type
+ * their tool selection lists without depending on the contracts pkg.
+ */
+export type { ToolProviderKind };

package/src/api/lib/code-tool.decorator.ts

@@ -0,0 +1,111 @@
+import type {
+  BiomeCodeToolDescriptor,
+  BiomeCodeToolMountHint,
+  BiomeCodeToolOutputKind,
+} from './code-tool-descriptor';
+
+/**
+ * Metadata key under which `@BiomeCodeTool` decorator data is
+ * stored via `reflect-metadata`. The biome's API service scans
+ * controllers for this key at boot, builds a manifest, and exposes
+ * it through `GET /code-tools-manifest`.
+ *
+ * Kept as a plain symbol so biome frameworks (NestJS, raw Express,
+ * Fastify) can discover decorated methods the same way regardless of
+ * which router they use.
+ */
+export const BIOME_CODE_TOOL_METADATA_KEY = Symbol.for(
+  'xema.biome.code-tool.descriptor',
+);
+
+export interface BiomeCodeToolDecoratorOptions {
+  readonly key: string;
+  readonly displayName: string;
+  readonly description: string;
+  /**
+   * JSON Schema (raw object) describing the input. Biome authors
+   * typically generate this from a Zod schema via
+   * `zodToJsonSchema(schema)` — kept as plain JSON Schema here so the
+   * SDK has no Zod runtime dependency.
+   */
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  readonly outputKind: BiomeCodeToolOutputKind;
+  readonly mount?: BiomeCodeToolMountHint;
+}
+
+/**
+ * Method decorator that flags a class method as the handler for one
+ * MCP code tool. The biome's API service is expected to expose this
+ * method at `POST /biome-code-tools/:key`; the discovery scanner
+ * builds the route table from these decorators.
+ *
+ * Usage:
+ *
+ *   ```ts
+ *   class EmailTools {
+ *     @BiomeCodeTool({
+ *       key: 'search-archive',
+ *       displayName: 'Search Email Archive',
+ *       description: 'Search archived emails by full-text query.',
+ *       inputSchema: searchArchiveJsonSchema,
+ *       outputKind: 'structured',
+ *     })
+ *     async searchArchive(args, ctx) { ... }
+ *   }
+ *   ```
+ *
+ * Tenancy: the platform service-token-validates every inbound call
+ * and stamps `CodeToolCtx`; handler code receives only scope-bound
+ * sub-clients, never raw credentials.
+ */
+export function BiomeCodeTool(
+  options: BiomeCodeToolDecoratorOptions,
+): MethodDecorator {
+  return ((
+    target: object,
+    propertyKey: string | symbol,
+    descriptor?: PropertyDescriptor,
+  ): void => {
+    void descriptor;
+    const desc: BiomeCodeToolDescriptor = {
+      key: options.key,
+      displayName: options.displayName,
+      description: options.description,
+      inputSchema: options.inputSchema,
+      outputKind: options.outputKind,
+      ...(options.mount ? { mount: options.mount } : {}),
+    };
+    const existing = readToolList(target) ?? [];
+    existing.push({ methodName: String(propertyKey), descriptor: desc });
+    setToolList(target, existing);
+  }) as MethodDecorator;
+}
+
+export interface RegisteredCodeTool {
+  readonly methodName: string;
+  readonly descriptor: BiomeCodeToolDescriptor;
+}
+
+/**
+ * Read all `@BiomeCodeTool`-decorated methods on a class.
+ * Discovery scanners use this to build the biome's tools-manifest.
+ */
+export function getRegisteredCodeTools(
+  target: object,
+): readonly RegisteredCodeTool[] {
+  return readToolList(target) ?? [];
+}
+
+function readToolList(target: object): RegisteredCodeTool[] | undefined {
+  const store = (target as Record<symbol, unknown>)[BIOME_CODE_TOOL_METADATA_KEY];
+  return Array.isArray(store) ? (store as RegisteredCodeTool[]) : undefined;
+}
+
+function setToolList(target: object, list: RegisteredCodeTool[]): void {
+  Object.defineProperty(target, BIOME_CODE_TOOL_METADATA_KEY, {
+    value: list,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+}

package/src/api/lib/mutation-context.ts

@@ -0,0 +1,49 @@
+/**
+ * Mutation context threaded through every service mutation — carries
+ * the actor identity and correlation ids needed for event publishing
+ * and audit trails.
+ *
+ * Canonical type shared across all biome services. Do NOT redefine
+ * per-service.
+ */
+export interface MutationContext {
+  actorId: string;
+  actorType: 'human' | 'agent' | 'service';
+  correlationId: string;
+  causationId?: string;
+}
+
+/**
+ * Minimal request-context shape required by biome controller helpers
+ * (`requireProjectId`, `mutationContext`). Structurally compatible with
+ * `platform-common`'s `RequestContext` — any `RequestContext` instance
+ * satisfies this interface without a cast.
+ */
+export interface BiomeMutationRequestContext {
+  orgId: string;
+  projectId?: string;
+  actorId: string;
+  /** Any actorType string is accepted; helpers normalise it to the MutationContext closed set. */
+  actorType: string;
+  correlationId: string;
+  causationId?: string;
+}
+
+/**
+ * Build a `MutationContext` from the request context. Normalises the
+ * raw `actorType` string to the closed set used by domain services.
+ */
+export function buildMutationContext(ctx: BiomeMutationRequestContext): MutationContext {
+  const actorType: MutationContext['actorType'] =
+    ctx.actorType === 'agent'
+      ? 'agent'
+      : ctx.actorType === 'service'
+        ? 'service'
+        : 'human';
+  return {
+    actorId: ctx.actorId,
+    actorType,
+    correlationId: ctx.correlationId,
+    ...(ctx.causationId ? { causationId: ctx.causationId } : {}),
+  };
+}

package/src/api/lib/pagination.ts

@@ -0,0 +1,17 @@
+/** Pagination metadata returned by list endpoints. */
+export interface PaginationMeta {
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}
+
+/**
+ * Assemble pagination metadata from a Prisma count result and the
+ * query parameters. `totalPages` is always at least 1 even on an
+ * empty result set so that pagination UI components don't need to
+ * guard for zero.
+ */
+export function paginationMeta(total: number, page: number, limit: number): PaginationMeta {
+  return { total, page, limit, totalPages: Math.max(1, Math.ceil(total / limit)) };
+}

package/src/api/lib/provider-kind-mirror.ts

@@ -0,0 +1,16 @@
+/**
+ * Mirror of `ToolProviderKind` from `@xemahq/kernel-contracts/mcp-tool` —
+ * inlined here so biome-api-sdk stays free of cross-package
+ * dependencies on the broader MCP contracts package. The string
+ * values MUST stay identical to the kernel enum.
+ *
+ * Biome authors typically don't need this; it's used internally by
+ * the code-tool descriptor types so downstream code that reads a
+ * biome's manifest gets a typed kind discriminator.
+ */
+export enum ToolProviderKind {
+  McpServer = 'mcp_server',
+  Catalog = 'catalog',
+  BiomeWorkflowTools = 'biome_workflow_tools',
+  BiomeCodeTools = 'biome_code_tools',
+}

package/src/api/lib/request-context.ts

@@ -0,0 +1,90 @@
+/**
+ * Authoritative request context the ingress shim injects on every
+ * call to a biome-shipped API. Biomes MUST NOT trust claim parsing
+ * inside their own handlers — the shim does the JWT validation, asserts
+ * the JWT's `xema_org_id` claim matches the `X-Org-Id` header, and
+ * stamps this shape into the request.
+ *
+ * Identical to `RequestContext` from `@xemahq/platform-common` by
+ * intent; redeclared here so the SDK stays free of platform-common
+ * imports (Kernel rule).
+ */
+export interface BiomeApiRequestContext {
+  readonly orgId: string;
+  readonly projectId?: string;
+  readonly installationId?: string;
+  readonly actorSubject: string;
+  readonly actorType: 'user' | 'service';
+  /**
+   * The biome id this API was deployed under. Surfaced so handlers
+   * can self-identify in logs without consulting env vars.
+   */
+  readonly biomeId: string;
+}
+
+/**
+ * Header names the ingress shim sets on every inbound call. Biome
+ * authors read them directly (cheap path) or use the SDK's
+ * `requireRequestContext(req)` helper.
+ */
+export const BIOME_API_HEADERS = {
+  orgId: 'x-org-id',
+  projectId: 'x-project-id',
+  installationId: 'x-installation-id',
+  actorSubject: 'x-actor-subject',
+  actorType: 'x-actor-type',
+  biomeId: 'x-biome-id',
+} as const;
+
+/**
+ * Pure extractor — runs in any handler shape (NestJS, Express, Fastify,
+ * standalone Node). Throws on missing required headers so biome
+ * handlers fail fast instead of operating on incomplete context.
+ */
+export function requireRequestContext(
+  headers: Readonly<Record<string, string | string[] | undefined>>,
+): BiomeApiRequestContext {
+  const orgId = header(headers, BIOME_API_HEADERS.orgId);
+  const actorSubject = header(headers, BIOME_API_HEADERS.actorSubject);
+  const actorTypeRaw = header(headers, BIOME_API_HEADERS.actorType);
+  const biomeId = header(headers, BIOME_API_HEADERS.biomeId);
+  if (!orgId || !actorSubject || !actorTypeRaw || !biomeId) {
+    throw new BiomeApiContextError(
+      'biome API request is missing one or more required headers — ingress shim did not inject context',
+    );
+  }
+  if (actorTypeRaw !== 'user' && actorTypeRaw !== 'service') {
+    throw new BiomeApiContextError(
+      `unknown actorType "${actorTypeRaw}" — expected "user" | "service"`,
+    );
+  }
+  const ctx: BiomeApiRequestContext = {
+    orgId,
+    actorSubject,
+    actorType: actorTypeRaw,
+    biomeId,
+  };
+  const projectId = header(headers, BIOME_API_HEADERS.projectId);
+  const installationId = header(headers, BIOME_API_HEADERS.installationId);
+  return {
+    ...ctx,
+    ...(projectId ? { projectId } : {}),
+    ...(installationId ? { installationId } : {}),
+  };
+}
+
+export class BiomeApiContextError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BiomeApiContextError';
+  }
+}
+
+function header(
+  headers: Readonly<Record<string, string | string[] | undefined>>,
+  name: string,
+): string | undefined {
+  const value = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(value)) return value[0];
+  return value;
+}

package/src/api/lib/route-registry-entry.ts

@@ -0,0 +1,35 @@
+/**
+ * Wire shape for a single route-registry entry biome-host-api writes
+ * to the Redis store the public ingress consults at request time
+ * (same primitive as the output surface gateway — see
+ * `.claude/plans/golden-floating-piglet.md` Phase 4).
+ *
+ * Each entry maps `<biomeName>.api.<base-domain>` to an upstream
+ * cluster-internal service. The ingress shim:
+ *   1. Looks up the entry by subdomain (Redis `GET`).
+ *   2. Validates the platform JWT + asserts `xema_org_id` claim matches
+ *      the request's tenant routing.
+ *   3. Strips the JWT, stamps `BIOME_API_HEADERS` from the request
+ *      context, proxies to the upstream.
+ *
+ * Biomes NEVER write to this registry directly — biome-host-api owns
+ * the lifecycle, removing the entry on uninstall.
+ */
+export interface BiomeApiRouteRegistryEntry {
+  readonly subdomain: string;
+  readonly biomeId: string;
+  readonly upstreamHost: string;
+  readonly upstreamPort: number;
+  readonly basePath: string;
+  /**
+   * Closed-set deployment lifecycle marker. `provisioning` blocks
+   * traffic until the underlying Helm release reports healthy;
+   * `disabled` returns 503 with a clear "admin disabled" message;
+   * `active` is the steady state.
+   */
+  readonly status: BiomeApiRouteStatus;
+  /** ISO-8601. Operators chart entry churn against this. */
+  readonly updatedAt: string;
+}
+
+export type BiomeApiRouteStatus = 'provisioning' | 'active' | 'disabled';

package/src/api/nest/controller-base.ts

@@ -0,0 +1,59 @@
+import { BadRequestException } from '@nestjs/common';
+
+import type { MutationContext, BiomeMutationRequestContext } from '../lib/mutation-context.js';
+
+/**
+ * Abstract base class for biome API controllers. Provides the two
+ * helpers that every biome controller needs:
+ *
+ * - `requireProjectId(ctx)` — asserts the request carries a project
+ *   scope and throws `400 Bad Request` if it doesn't.
+ * - `mutationContext(ctx)` — builds the `MutationContext` passed to
+ *   domain-service mutation methods.
+ *
+ * The `ctx` parameter is typed as `BiomeMutationRequestContext`, which
+ * is structurally compatible with `platform-common`'s `RequestContext`
+ * so no cast is needed at call sites.
+ *
+ * @example
+ *   @Controller('things')
+ *   export class ThingsController extends BiomeApiControllerBase {
+ *     constructor(private readonly service: ThingsService) {
+ *       super();
+ *     }
+ *
+ *     @Post()
+ *     create(@Body() dto: CreateDto, @Ctx() ctx: RequestContext) {
+ *       return this.service.create(
+ *         ctx.orgId,
+ *         this.requireProjectId(ctx),
+ *         dto,
+ *         this.mutationContext(ctx),
+ *       );
+ *     }
+ *   }
+ */
+export abstract class BiomeApiControllerBase {
+  protected requireProjectId(ctx: BiomeMutationRequestContext): string {
+    const projectId = ctx.projectId;
+    if (!projectId) {
+      throw new BadRequestException('X-Project-Id header is required for this endpoint');
+    }
+    return projectId;
+  }
+
+  protected mutationContext(ctx: BiomeMutationRequestContext): MutationContext {
+    const actorType: MutationContext['actorType'] =
+      ctx.actorType === 'agent'
+        ? 'agent'
+        : ctx.actorType === 'service'
+          ? 'service'
+          : 'human';
+    return {
+      actorId: ctx.actorId,
+      actorType,
+      correlationId: ctx.correlationId,
+      ...(ctx.causationId ? { causationId: ctx.causationId } : {}),
+    };
+  }
+}

package/src/api/nest/events/events.controller.ts

@@ -0,0 +1,48 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Headers,
+  HttpCode,
+  HttpStatus,
+  Logger,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { ApiExcludeController, ApiTags } from '@nestjs/swagger';
+import { EventHubWebhookGuard } from '@xemahq/event-hub-client';
+import { EventDispatcherService, handleCloudEventWebhook } from '@xemahq/events/nest';
+
+/**
+ * Shared CloudEvent webhook ingress for biome services. Accepts
+ * events pushed by event-hub-api and dispatches them to whichever
+ * `@OnCloudEvent`-decorated handler methods are registered.
+ *
+ * Add this controller to the biome's `EventsModule` and register
+ * domain-specific event handlers as providers in that module.
+ */
+@ApiTags('Webhooks')
+@ApiExcludeController()
+@Controller('webhooks')
+export class PluginEventsController {
+  private readonly logger = new Logger(PluginEventsController.name);
+
+  constructor(private readonly dispatcher: EventDispatcherService) {}
+
+  @Post('events')
+  @HttpCode(HttpStatus.OK)
+  @UseGuards(EventHubWebhookGuard)
+  async handleWebhook(
+    @Body() body: unknown,
+    @Headers() headers: Record<string, string>,
+  ): Promise<{ received: boolean }> {
+    try {
+      await handleCloudEventWebhook(body, headers, this.dispatcher);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.logger.warn(`Rejecting malformed CloudEvent webhook: ${message}`);
+      throw new BadRequestException(message);
+    }
+    return { received: true };
+  }
+}