@beignet/core 0.0.36 → 0.0.37

package/src/contracts/contract-group.ts

@@ -5,6 +5,10 @@ import {
   responsesFromErrors,
 } from "./catalog-errors.js";
 import { ContractBuilder } from "./contract-builder.js";
+import {
+  assertValidContractDeprecation,
+  type ContractDeprecationMeta,
+} from "./lifecycle.js";
 import { mergeContractMeta } from "./metadata.js";
 import { parsePathTemplate } from "./path-template.js";
 import type {
@@ -164,6 +168,27 @@ export class ContractGroup<
     });
   }
 
+  /**
+   * Mark every contract created from this group as deprecated.
+   */
+  deprecated<const TDeprecation extends ContractDeprecationMeta>(
+    deprecation: TDeprecation,
+  ): ContractGroup<
+    TSharedResponses,
+    MergeContractMeta<TSharedMeta, { deprecation: TDeprecation }>,
+    TSharedHeaders,
+    TPathPrefix
+  > {
+    assertValidContractDeprecation(deprecation, this._namespace || "group");
+    return new ContractGroup({
+      namespace: this._namespace,
+      meta: mergeContractMeta(this._meta, { deprecation }),
+      responses: this._responses,
+      headers: this._headers,
+      pathPrefix: this._pathPrefix,
+    });
+  }
+
   /**
    * Add shared route-owned response schemas to contracts created from this group.
    *

package/src/contracts/index.ts

@@ -35,6 +35,14 @@ export {
   type ResolveContract,
   resolveContract,
 } from "./contract-like.js";
+/**
+ * Contract lifecycle metadata and errors.
+ */
+export {
+  type ContractDeprecationMeta,
+  ContractLifecycleError,
+  type ContractLifecycleFindingCode,
+} from "./lifecycle.js";
 /**
  * OpenAPI operation metadata type.
  */

package/src/contracts/lifecycle.ts

@@ -0,0 +1,236 @@
+import type { HttpContractConfig } from "./types.js";
+
+/**
+ * Lifecycle metadata for an HTTP contract that external clients should stop
+ * using.
+ */
+export type ContractDeprecationMeta = {
+  /** UTC ISO 8601 timestamp when the contract became deprecated. */
+  since: string;
+  /** Optional human-readable explanation. */
+  reason?: string;
+  /** UTC ISO 8601 timestamp after which the contract may stop being served. */
+  sunset?: string;
+  /** URI reference for the preferred replacement operation. */
+  replacement?: string;
+  /** Absolute HTTP(S) URL with migration or deprecation documentation. */
+  documentation?: string;
+};
+
+/** Stable code identifying invalid lifecycle or operation metadata. */
+export type ContractLifecycleFindingCode =
+  | "INVALID_DEPRECATION_SINCE"
+  | "INVALID_DEPRECATION_SUNSET"
+  | "DEPRECATION_SUNSET_BEFORE_SINCE"
+  | "INVALID_DEPRECATION_REASON"
+  | "INVALID_DEPRECATION_REPLACEMENT"
+  | "INVALID_DEPRECATION_DOCUMENTATION"
+  | "INVALID_OPERATION_ID";
+
+/** Error raised when contract lifecycle metadata is malformed. */
+export class ContractLifecycleError extends Error {
+  /** Stable machine-readable finding code. */
+  readonly code: ContractLifecycleFindingCode;
+  /** Name of the invalid contract, or the group label during group setup. */
+  readonly contract: string;
+
+  constructor(args: {
+    code: ContractLifecycleFindingCode;
+    contract: string;
+    message: string;
+  }) {
+    super(args.message);
+    this.name = "ContractLifecycleError";
+    this.code = args.code;
+    this.contract = args.contract;
+  }
+}
+
+const ISO_8601_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+const INVALID_URI_REFERENCE_CHARACTERS = /[\s<>"\\]/;
+const INVALID_PERCENT_ENCODING = /%(?![0-9A-Fa-f]{2})/;
+
+function parseUtcTimestamp(value: string): number | undefined {
+  if (!ISO_8601_UTC.test(value)) return undefined;
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)) return undefined;
+
+  const canonical = new Date(timestamp).toISOString();
+  if (value !== canonical && value !== canonical.replace(".000Z", "Z")) {
+    return undefined;
+  }
+
+  return timestamp;
+}
+
+function assertNonEmptyOptionalString(args: {
+  value: unknown;
+  field: "reason" | "replacement";
+  code: ContractLifecycleFindingCode;
+  contract: string;
+}): string | undefined {
+  if (args.value === undefined) return undefined;
+  if (typeof args.value !== "string" || args.value.trim().length === 0) {
+    throw new ContractLifecycleError({
+      code: args.code,
+      contract: args.contract,
+      message: `Contract "${args.contract}" deprecation ${args.field} must be a non-empty string.`,
+    });
+  }
+  return args.value;
+}
+
+/** Validate deprecation metadata supplied by builders or raw contract configs. */
+export function assertValidContractDeprecation(
+  deprecation: unknown,
+  contract: string,
+): asserts deprecation is ContractDeprecationMeta {
+  if (typeof deprecation !== "object" || deprecation === null) {
+    throw new ContractLifecycleError({
+      code: "INVALID_DEPRECATION_SINCE",
+      contract,
+      message: `Contract "${contract}" deprecation metadata must include a valid "since" timestamp.`,
+    });
+  }
+
+  const metadata = deprecation as Record<string, unknown>;
+  const since =
+    typeof metadata.since === "string"
+      ? parseUtcTimestamp(metadata.since)
+      : undefined;
+  if (since === undefined) {
+    throw new ContractLifecycleError({
+      code: "INVALID_DEPRECATION_SINCE",
+      contract,
+      message: `Contract "${contract}" deprecation "since" must be a valid UTC ISO 8601 timestamp such as 2026-07-11T00:00:00Z.`,
+    });
+  }
+
+  let sunset: number | undefined;
+  if (metadata.sunset !== undefined) {
+    sunset =
+      typeof metadata.sunset === "string"
+        ? parseUtcTimestamp(metadata.sunset)
+        : undefined;
+    if (sunset === undefined) {
+      throw new ContractLifecycleError({
+        code: "INVALID_DEPRECATION_SUNSET",
+        contract,
+        message: `Contract "${contract}" deprecation "sunset" must be a valid UTC ISO 8601 timestamp.`,
+      });
+    }
+    if (sunset < since) {
+      throw new ContractLifecycleError({
+        code: "DEPRECATION_SUNSET_BEFORE_SINCE",
+        contract,
+        message: `Contract "${contract}" deprecation "sunset" must not be earlier than "since".`,
+      });
+    }
+  }
+
+  assertNonEmptyOptionalString({
+    value: metadata.reason,
+    field: "reason",
+    code: "INVALID_DEPRECATION_REASON",
+    contract,
+  });
+  const replacement = assertNonEmptyOptionalString({
+    value: metadata.replacement,
+    field: "replacement",
+    code: "INVALID_DEPRECATION_REPLACEMENT",
+    contract,
+  });
+  let replacementIsValid = true;
+  if (replacement) {
+    try {
+      new URL(replacement, "https://beignet.invalid");
+    } catch {
+      replacementIsValid = false;
+    }
+  }
+  if (
+    replacement &&
+    (!replacementIsValid ||
+      INVALID_URI_REFERENCE_CHARACTERS.test(replacement) ||
+      INVALID_PERCENT_ENCODING.test(replacement))
+  ) {
+    throw new ContractLifecycleError({
+      code: "INVALID_DEPRECATION_REPLACEMENT",
+      contract,
+      message: `Contract "${contract}" deprecation "replacement" must be a valid URI reference without whitespace.`,
+    });
+  }
+
+  if (metadata.documentation !== undefined) {
+    let documentation: URL | undefined;
+    if (typeof metadata.documentation === "string") {
+      try {
+        documentation = new URL(metadata.documentation);
+      } catch {
+        documentation = undefined;
+      }
+    }
+    if (
+      !documentation ||
+      (documentation.protocol !== "http:" &&
+        documentation.protocol !== "https:") ||
+      INVALID_URI_REFERENCE_CHARACTERS.test(metadata.documentation as string)
+    ) {
+      throw new ContractLifecycleError({
+        code: "INVALID_DEPRECATION_DOCUMENTATION",
+        contract,
+        message: `Contract "${contract}" deprecation "documentation" must be an absolute HTTP(S) URL.`,
+      });
+    }
+  }
+}
+
+/** Return and validate the operation ID used by OpenAPI and route registries. */
+export function getContractOperationId(
+  contract: Pick<HttpContractConfig, "name" | "metadata">,
+): string {
+  const operationId = contract.metadata.openapi?.operationId ?? contract.name;
+  if (
+    typeof operationId !== "string" ||
+    operationId.trim().length === 0 ||
+    operationId !== operationId.trim()
+  ) {
+    throw new ContractLifecycleError({
+      code: "INVALID_OPERATION_ID",
+      contract: contract.name,
+      message: `Contract "${contract.name}" operationId must be a non-empty string without surrounding whitespace.`,
+    });
+  }
+  return operationId;
+}
+
+/** Validate lifecycle metadata on a complete contract definition. */
+export function assertValidContractLifecycle(
+  contract: Pick<HttpContractConfig, "name" | "metadata">,
+): void {
+  getContractOperationId(contract);
+  const deprecation = contract.metadata.deprecation;
+  if (deprecation !== undefined) {
+    assertValidContractDeprecation(deprecation, contract.name);
+  }
+}
+
+/** Build standards-based HTTP response headers for a deprecated contract. */
+export function contractLifecycleResponseHeaders(
+  contract: Pick<HttpContractConfig, "name" | "metadata">,
+): Record<string, string> {
+  const deprecation = contract.metadata.deprecation;
+  if (deprecation === undefined) return {};
+  assertValidContractDeprecation(deprecation, contract.name);
+
+  const headers: Record<string, string> = {
+    Deprecation: `@${Math.floor(Date.parse(deprecation.since) / 1000)}`,
+  };
+  if (deprecation.sunset) {
+    headers.Sunset = new Date(deprecation.sunset).toUTCString();
+  }
+  if (deprecation.documentation) {
+    headers.Link = `<${deprecation.documentation}>; rel="deprecation"`;
+  }
+  return headers;
+}

package/src/contracts/types.ts

@@ -1,5 +1,6 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { IdempotencyMeta } from "../idempotency/index.js";
+import type { ContractDeprecationMeta } from "./lifecycle.js";
 import type { OpenAPIOperationMeta } from "./openapi-meta.js";
 import type { RateLimitMeta } from "./rate-limit.js";
 
@@ -228,6 +229,10 @@ export type ContractMeta = {
    * OpenAPI operation metadata.
    */
   openapi?: OpenAPIOperationMeta;
+  /**
+   * External API lifecycle metadata for a deprecated contract.
+   */
+  deprecation?: ContractDeprecationMeta;
   /**
    * Optional rate limit configuration for this contract.
    *

package/src/openapi/index.ts

@@ -6,6 +6,7 @@
 
 import {
   type AnyContract,
+  type ContractDeprecationMeta,
   type ContractLike,
   getContractHeaderSchemas,
   methodSupportsRequestBody,
@@ -13,6 +14,10 @@ import {
   resolveContract,
   STANDARD_ERROR_RESPONSE_SCHEMA,
 } from "../contracts/index.js";
+import {
+  assertValidContractLifecycle,
+  getContractOperationId,
+} from "../contracts/lifecycle.js";
 import {
   comparePathParamsToTemplate,
   formatPathParamsMismatch,
@@ -235,6 +240,8 @@ export interface OperationObject {
    * Whether the operation is deprecated.
    */
   deprecated?: boolean;
+  /** Beignet lifecycle details for a deprecated operation. */
+  "x-beignet-deprecation"?: ContractDeprecationMeta;
   /**
    * External documentation.
    */
@@ -409,9 +416,20 @@ export function contractsToOpenAPI(
       createZodSchemaConverter(),
     ],
   };
+  const operationIds = new Map<string, string>();
 
   for (const contract of contracts) {
     const config = resolveContract(contract);
+    assertValidContractLifecycle(config);
+    const operationId = getContractOperationId(config);
+    const route = `${config.method} ${config.path}`;
+    const conflictingRoute = operationIds.get(operationId);
+    if (conflictingRoute) {
+      throw new Error(
+        `Duplicate OpenAPI operationId: "${operationId}" is used by both ${conflictingRoute} and ${route}. Operation IDs must be unique within an OpenAPI document.`,
+      );
+    }
+    operationIds.set(operationId, route);
     addContractToPaths(config, paths, state);
   }
 
@@ -454,13 +472,15 @@ function addContractToPaths(
   const pathItem = paths[pathKey];
 
   const meta = contract.metadata?.openapi;
+  const deprecation = contract.metadata?.deprecation;
 
   const operation: OperationObject = {
-    operationId: meta?.operationId ?? contract.name,
+    operationId: getContractOperationId(contract),
     summary: meta?.summary,
     description: meta?.description,
     tags: meta?.tags,
-    deprecated: meta?.deprecated,
+    deprecated: deprecation ? true : meta?.deprecated,
+    "x-beignet-deprecation": deprecation,
     externalDocs: meta?.externalDocs,
     security: meta?.security,
     parameters: [],

package/src/server/request-executor.ts

@@ -72,6 +72,7 @@ import {
   responseForHooks,
   responseOwnerFor,
   toContractViolationResponse,
+  withContractLifecycleHeaders,
   withFrameworkErrorOwnerHeader,
 } from "./response-finalization.js";
 import {
@@ -947,6 +948,7 @@ export function createRequestExecutor<
           finalOwner,
         );
       }
+      finalResponse = withContractLifecycleHeaders(finalResponse, contract);
       finalResponse = withoutHeadResponseBody(finalResponse, req.method);
       stages.sendMs = performance.now() - sendStartedAt;
 
@@ -987,7 +989,10 @@ export function createRequestExecutor<
         },
       );
       const response = withoutHeadResponseBody(
-        normalizeHttpResponse(result.response),
+        withContractLifecycleHeaders(
+          normalizeHttpResponse(result.response),
+          contract,
+        ),
         req.method,
       );
       if (isWebResponse(response)) {

package/src/server/response-finalization.ts

@@ -3,6 +3,7 @@ import {
   type ContractErrorDefinition,
   type HttpContractConfig,
 } from "../contracts/index.js";
+import { contractLifecycleResponseHeaders } from "../contracts/lifecycle.js";
 import {
   createErrorResponseBody,
   isErrorResponseBody,
@@ -74,6 +75,63 @@ export function withFrameworkErrorOwnerHeader(
   };
 }
 
+function setRecordHeader(
+  headers: Record<string, string>,
+  name: string,
+  value: string,
+): void {
+  const existingName = Object.keys(headers).find(
+    (key) => key.toLowerCase() === name.toLowerCase(),
+  );
+  if (existingName && existingName !== name) {
+    delete headers[existingName];
+  }
+  headers[name] = value;
+}
+
+/** Apply contract-owned deprecation headers to any response representation. */
+export function withContractLifecycleHeaders(
+  res: HttpResponse,
+  contract: HttpContractConfig,
+): HttpResponse {
+  const lifecycleHeaders = contractLifecycleResponseHeaders(contract);
+  if (Object.keys(lifecycleHeaders).length === 0) return res;
+
+  if (isWebResponse(res)) {
+    const headers = new Headers(res.headers);
+    for (const [name, value] of Object.entries(lifecycleHeaders)) {
+      if (name.toLowerCase() === "link" && headers.has(name)) {
+        headers.append(name, value);
+      } else {
+        headers.set(name, value);
+      }
+    }
+    return new Response(res.body, {
+      status: res.status,
+      statusText: res.statusText,
+      headers,
+    });
+  }
+
+  const headers = { ...(res.headers ?? {}) };
+  for (const [name, value] of Object.entries(lifecycleHeaders)) {
+    if (name.toLowerCase() === "link") {
+      const existingName = Object.keys(headers).find(
+        (key) => key.toLowerCase() === "link",
+      );
+      const existing = existingName ? headers[existingName] : undefined;
+      setRecordHeader(
+        headers,
+        name,
+        existing ? `${existing}, ${value}` : value,
+      );
+    } else {
+      setRecordHeader(headers, name, value);
+    }
+  }
+  return { ...res, headers };
+}
+
 export function responseOwnerFor(
   res: HttpResponse,
   owner?: ResponseOwner,

package/src/server/server.ts

@@ -3,6 +3,10 @@ import {
   type HttpContractConfig,
   methodSupportsRequestBody,
 } from "../contracts/index.js";
+import {
+  assertValidContractLifecycle,
+  getContractOperationId,
+} from "../contracts/lifecycle.js";
 import {
   comparePathParamsToTemplate,
   formatPathParamsMismatch,
@@ -539,6 +543,7 @@ export async function createServer<
   const registeredPaths = new Set<string>();
   const registeredShapes = new Map<string, string>();
   const registeredNames = new Map<string, string>();
+  const registeredOperationIds = new Map<string, string>();
 
   const registerRoute = <C extends HttpContractConfig>(
     contract: C,
@@ -546,6 +551,7 @@ export async function createServer<
     routeHooks: readonly RouteHook<unknown, object>[] = [],
     responseValidationExemptStatus?: number,
   ): void => {
+    assertValidContractLifecycle(contract);
     if (contract.body && !methodSupportsRequestBody(contract.method)) {
       throw new Error(
         `Request bodies are not supported for ${contract.method} contracts. Use POST, PUT, or PATCH for contract request bodies.`,
@@ -572,6 +578,13 @@ export async function createServer<
         `Duplicate contract name: "${contract.name}" is registered for both ${conflictingName} and ${routeKey}. Contract names must be unique because typed clients, OpenAPI operations, and devtools key on them.`,
       );
     }
+    const operationId = getContractOperationId(contract);
+    const conflictingOperationId = registeredOperationIds.get(operationId);
+    if (conflictingOperationId) {
+      throw new Error(
+        `Duplicate OpenAPI operationId: "${operationId}" is registered for both ${conflictingOperationId} and ${routeKey}. Operation IDs must be unique across the registered route surface.`,
+      );
+    }
     if (contract.pathParams) {
       const shape = getObjectSchemaShape(contract.pathParams);
       if (shape) {
@@ -590,6 +603,7 @@ export async function createServer<
     registeredPaths.add(routeKey);
     registeredShapes.set(shapeRouteKey, routeKey);
     registeredNames.set(contract.name, routeKey);
+    registeredOperationIds.set(operationId, routeKey);
 
     const builtHandler = buildHandler(
       options,

package/dist/domain/events.d.ts

@@ -1,44 +0,0 @@
-import type { EventDef, InferEventPayload, StandardSchema } from "../events/index.js";
-/**
- * Domain event definition with a stable name and payload schema.
- */
-export type DomainEventDef<Name extends string = string, Payload extends StandardSchema = StandardSchema> = EventDef<Name, Payload>;
-/**
- * Infer the payload type from a DomainEventDef.
- *
- * @example
- * ```ts
- * const UserRegistered = defineDomainEvent(
- *   "user.registered",
- *   z.object({
- *     userId: z.string(),
- *     email: z.string().email(),
- *   })
- * );
- *
- * type Payload = InferEventPayload<typeof UserRegistered>;
- * // { userId: string; email: string }
- * ```
- */
-export type { InferEventPayload };
-/**
- * Create a new domain event definition.
- *
- * This is a domain-focused alias around `defineEvent(...)` for applications
- * that separate domain events from integration events.
- *
- * @example
- * ```ts
- * const UserRegistered = defineDomainEvent(
- *   "user.registered",
- *   z.object({
- *     userId: z.string(),
- *     email: z.string().email(),
- *   })
- * );
- *
- * type UserRegistered = typeof UserRegistered;
- * ```
- */
-export declare function defineDomainEvent<Name extends string, Payload extends StandardSchema>(name: Name, payload: Payload): DomainEventDef<Name, Payload>;
-//# sourceMappingURL=events.d.ts.map

package/dist/domain/events.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/domain/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,iBAAiB,EACjB,cAAc,EACf,MAAM,oBAAoB,CAAC;AAG5B;;GAEG;AACH,MAAM,MAAM,cAAc,CACxB,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,OAAO,SAAS,cAAc,GAAG,cAAc,IAC7C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,SAAS,MAAM,EACnB,OAAO,SAAS,cAAc,EAC9B,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAE7D"}

package/dist/domain/events.js

@@ -1,24 +0,0 @@
-import { defineEvent } from "../events/index.js";
-/**
- * Create a new domain event definition.
- *
- * This is a domain-focused alias around `defineEvent(...)` for applications
- * that separate domain events from integration events.
- *
- * @example
- * ```ts
- * const UserRegistered = defineDomainEvent(
- *   "user.registered",
- *   z.object({
- *     userId: z.string(),
- *     email: z.string().email(),
- *   })
- * );
- *
- * type UserRegistered = typeof UserRegistered;
- * ```
- */
-export function defineDomainEvent(name, payload) {
-    return defineEvent(name, { payload });
-}
-//# sourceMappingURL=events.js.map

package/dist/domain/events.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/domain/events.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA6BjD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAG/B,IAAU,EAAE,OAAgB;IAC5B,OAAO,WAAW,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AACxC,CAAC"}