@beignet/core 0.0.3 → 0.0.4

package/src/contracts/catalog-errors.ts

@@ -0,0 +1,115 @@
+import type {
+  ContractErrorDefinition,
+  ContractErrorResponses,
+  ContractMeta,
+  ContractResponses,
+} from "./types.js";
+import { STANDARD_ERROR_RESPONSE_SCHEMA } from "./types.js";
+
+function isContractErrorDefinition(
+  value: unknown,
+): value is ContractErrorDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { code?: unknown }).code === "string" &&
+    typeof (value as { status?: unknown }).status === "number" &&
+    typeof (value as { message?: unknown }).message === "string"
+  );
+}
+
+/**
+ * Extract catalog error definitions declared in contract metadata.
+ */
+export function catalogErrorsFromMeta(
+  metadata: ContractMeta,
+): ContractErrorResponses {
+  const errors = metadata.errors;
+  if (typeof errors !== "object" || errors === null) return {};
+
+  const catalog: ContractErrorResponses = {};
+  for (const [key, definition] of Object.entries(errors)) {
+    if (isContractErrorDefinition(definition)) {
+      catalog[key] = definition;
+    }
+  }
+  return catalog;
+}
+
+/**
+ * Convert catalog error definitions into standard envelope response schemas.
+ */
+export function responsesFromErrors(
+  errors: ContractErrorResponses,
+): ContractResponses {
+  const responses: ContractResponses = {};
+  for (const error of Object.values(errors)) {
+    responses[error.status] = STANDARD_ERROR_RESPONSE_SCHEMA;
+  }
+  return responses;
+}
+
+/**
+ * Merge catalog errors already declared in metadata with new declarations.
+ *
+ * Later declarations win when the same catalog key is declared twice.
+ */
+export function mergeCatalogErrors(
+  metadata: ContractMeta,
+  errorDefs: ContractErrorResponses,
+): ContractErrorResponses {
+  return { ...catalogErrorsFromMeta(metadata), ...errorDefs };
+}
+
+function catalogErrorStatuses(metadata: ContractMeta): Set<string> {
+  return new Set(
+    Object.values(catalogErrorsFromMeta(metadata)).map((error) =>
+      String(error.status),
+    ),
+  );
+}
+
+/**
+ * Reject `.errors()` statuses that collide with custom response schemas.
+ *
+ * Statuses declared by earlier `.errors()` calls are allowed: catalog errors
+ * share the standard error envelope, so multiple codes can map to one status.
+ */
+export function assertErrorsAvoidCustomResponseStatuses(
+  metadata: ContractMeta,
+  responses: ContractResponses,
+  nextErrorResponses: ContractResponses,
+): void {
+  const existingErrorStatuses = catalogErrorStatuses(metadata);
+  const customStatuses = new Set(
+    Object.keys(responses).filter(
+      (status) => !existingErrorStatuses.has(status),
+    ),
+  );
+  const conflicts = Object.keys(nextErrorResponses).filter((status) =>
+    customStatuses.has(status),
+  );
+  if (conflicts.length) {
+    throw new Error(
+      `.errors() cannot declare status ${conflicts.join(", ")} because a response schema for that status already exists. Use .responses() without .errors() when you need a custom error response body.`,
+    );
+  }
+}
+
+/**
+ * Reject `.responses()` statuses already declared by catalog errors.
+ */
+export function assertResponsesAvoidCatalogErrorStatuses(
+  metadata: ContractMeta,
+  next: ContractResponses,
+): void {
+  const errorStatuses = catalogErrorStatuses(metadata);
+  const conflicts = Object.keys(next).filter((status) =>
+    errorStatuses.has(status),
+  );
+  if (conflicts.length) {
+    throw new Error(
+      `.responses() cannot declare status ${conflicts.join(", ")} because that status is already declared by .errors(). Use .responses() without .errors() when you need a custom error response body.`,
+    );
+  }
+}

package/src/contracts/contract-builder.ts

@@ -1,6 +1,12 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { OpenAPIOperationMeta } from "./openapi-meta";
-import { parsePathTemplate } from "./path-template";
+import {
+  assertErrorsAvoidCustomResponseStatuses,
+  assertResponsesAvoidCatalogErrorStatuses,
+  mergeCatalogErrors,
+  responsesFromErrors,
+} from "./catalog-errors.js";
+import type { OpenAPIOperationMeta } from "./openapi-meta.js";
+import { parsePathTemplate } from "./path-template.js";
 import type {
   BodyHttpMethod,
   ContractErrorResponses,
@@ -9,67 +15,13 @@ import type {
   ContractResponses,
   HttpContractConfig,
   HttpMethod,
+  MergedContractErrorResponses,
+  OmitMetaKeys,
   ResponsesFromErrorDefinitions,
   StandardSchema,
-} from "./types";
-import {
-  methodSupportsRequestBody,
-  STANDARD_ERROR_RESPONSE_SCHEMA,
-} from "./types";
-import { generateContractName } from "./utils";
-
-function responsesFromErrors(
-  errors: ContractErrorResponses,
-): ContractResponses {
-  const responses: ContractResponses = {};
-  for (const error of Object.values(errors)) {
-    responses[error.status] = STANDARD_ERROR_RESPONSE_SCHEMA;
-  }
-  return responses;
-}
-
-function assertNoResponseStatusConflicts(
-  current: ContractResponses,
-  next: ContractResponses,
-): void {
-  const currentStatuses = new Set(Object.keys(current));
-  const conflicts = Object.keys(next).filter((status) =>
-    currentStatuses.has(status),
-  );
-  if (conflicts.length) {
-    throw new Error(
-      `.errors() cannot declare status ${conflicts.join(", ")} because a response schema for that status already exists. Use .responses() without .errors() when you need a custom error response body.`,
-    );
-  }
-}
-
-function assertNoCatalogErrorStatusConflicts(
-  metadata: ContractMeta,
-  next: ContractResponses,
-): void {
-  const errors = metadata.errors;
-  if (typeof errors !== "object" || errors === null) return;
-
-  const errorStatuses = new Set(
-    Object.values(errors)
-      .map((error) =>
-        typeof error === "object" &&
-        error !== null &&
-        typeof (error as { status?: unknown }).status === "number"
-          ? String((error as { status: number }).status)
-          : undefined,
-      )
-      .filter((status): status is string => status !== undefined),
-  );
-  const conflicts = Object.keys(next).filter((status) =>
-    errorStatuses.has(status),
-  );
-  if (conflicts.length) {
-    throw new Error(
-      `.responses() cannot declare status ${conflicts.join(", ")} because that status is already declared by .errors(). Use .responses() without .errors() when you need a custom error response body.`,
-    );
-  }
-}
+} from "./types.js";
+import { methodSupportsRequestBody } from "./types.js";
+import { generateContractName } from "./utils.js";
 
 /**
  * Fluent builder for one HTTP contract.
@@ -397,7 +349,7 @@ export class ContractBuilder<
     TMeta,
     TPath
   > {
-    assertNoCatalogErrorStatusConflicts(this._meta, responseSchemas);
+    assertResponsesAvoidCatalogErrorStatuses(this._meta, responseSchemas);
     return new ContractBuilder({
       kind: this.kind,
       name: this.name,
@@ -421,8 +373,11 @@ export class ContractBuilder<
    * Declare route-owned application errors from an error catalog.
    *
    * Catalog errors use Beignet's standard error response envelope and remain
-   * distinguishable from framework-owned errors. Use `.responses()` when a
-   * route needs a custom error response body instead of catalog semantics.
+   * distinguishable from framework-owned errors. Declarations merge with
+   * previously declared catalog errors, including shared group errors; later
+   * declarations win when the same catalog key is declared twice. Use
+   * `.responses()` when a route needs a custom error response body instead of
+   * catalog semantics.
    */
   errors<TErrorDefs extends ContractErrorResponses>(
     errorDefs: TErrorDefs,
@@ -434,11 +389,17 @@ export class ContractBuilder<
     THeaders,
     Omit<TResponses, keyof ResponsesFromErrorDefinitions<TErrorDefs>> &
       ResponsesFromErrorDefinitions<TErrorDefs>,
-    Omit<TMeta, "errors"> & { errors: TErrorDefs },
+    OmitMetaKeys<TMeta, "errors"> & {
+      errors: MergedContractErrorResponses<TMeta, TErrorDefs>;
+    },
     TPath
   > {
     const errorResponses = responsesFromErrors(errorDefs);
-    assertNoResponseStatusConflicts(this._responses, errorResponses);
+    assertErrorsAvoidCustomResponseStatuses(
+      this._meta,
+      this._responses,
+      errorResponses,
+    );
     return new ContractBuilder({
       kind: this.kind,
       name: this.name,
@@ -460,8 +421,10 @@ export class ContractBuilder<
         ResponsesFromErrorDefinitions<TErrorDefs>,
       metadata: {
         ...this._meta,
-        errors: errorDefs,
-      } as Omit<TMeta, "errors"> & { errors: TErrorDefs },
+        errors: mergeCatalogErrors(this._meta, errorDefs),
+      } as unknown as OmitMetaKeys<TMeta, "errors"> & {
+        errors: MergedContractErrorResponses<TMeta, TErrorDefs>;
+      },
     });
   }
 
@@ -480,7 +443,7 @@ export class ContractBuilder<
     TBody,
     THeaders,
     TResponses,
-    Omit<TMeta, keyof TNewMeta> & TNewMeta,
+    OmitMetaKeys<TMeta, keyof TNewMeta> & TNewMeta,
     TPath
   > {
     return new ContractBuilder({
@@ -498,7 +461,7 @@ export class ContractBuilder<
       metadata: {
         ...this._meta,
         ...newMeta,
-      } as unknown as Omit<TMeta, keyof TNewMeta> & TNewMeta,
+      } as unknown as OmitMetaKeys<TMeta, keyof TNewMeta> & TNewMeta,
     });
   }
 
@@ -542,9 +505,9 @@ export class ContractBuilder<
 }
 
 /**
- * Options for creating one contract with `createContract(...)`.
+ * Options for creating one contract with `defineContract(...)`.
  */
-export type CreateContractOptions<
+export type DefineContractOptions<
   TMethod extends HttpMethod = HttpMethod,
   TPath extends string = string,
 > = {
@@ -559,13 +522,13 @@ export type CreateContractOptions<
 /**
  * Create a new HTTP contract builder.
  *
- * Most apps prefer `createContractGroup().namespace(...).prefix(...)` for
+ * Most apps prefer `defineContractGroup().namespace(...).prefix(...)` for
  * related feature contracts. Use this lower-level factory when a standalone
  * contract is clearer.
  *
  * @example
  * ```ts
- * const getTodo = createContract({
+ * const getTodo = defineContract({
  *   method: "GET",
  *   path: "/api/todos/:id",
  * })
@@ -576,11 +539,11 @@ export type CreateContractOptions<
  * @param options - HTTP method, path template, and optional contract name.
  * @returns A fluent contract builder.
  */
-export function createContract<
+export function defineContract<
   TMethod extends HttpMethod,
   const TPath extends string,
 >(
-  options: CreateContractOptions<TMethod, TPath>,
+  options: DefineContractOptions<TMethod, TPath>,
 ): ContractBuilder<
   TMethod,
   null,

package/src/contracts/contract-group.ts

@@ -1,16 +1,23 @@
-import { ContractBuilder } from "./contract-builder";
-import { parsePathTemplate } from "./path-template";
+import {
+  assertErrorsAvoidCustomResponseStatuses,
+  assertResponsesAvoidCatalogErrorStatuses,
+  mergeCatalogErrors,
+  responsesFromErrors,
+} from "./catalog-errors.js";
+import { ContractBuilder } from "./contract-builder.js";
+import { parsePathTemplate } from "./path-template.js";
 import type {
   ContractErrorResponses,
   ContractHeaderSchemas,
   ContractMeta,
   ContractResponses,
   HttpMethod,
+  MergedContractErrorResponses,
+  OmitMetaKeys,
   ResponsesFromErrorDefinitions,
   StandardSchema,
-} from "./types";
-import { STANDARD_ERROR_RESPONSE_SCHEMA } from "./types";
-import { generateContractName } from "./utils";
+} from "./types.js";
+import { generateContractName } from "./utils.js";
 
 type TrimLeadingSlash<T extends string> = T extends `/${infer Rest}`
   ? TrimLeadingSlash<Rest>
@@ -49,59 +56,6 @@ function joinPathPrefix(prefix: string, path: string): string {
   return `/${segments.join("/")}`;
 }
 
-function responsesFromErrors(
-  errors: ContractErrorResponses,
-): ContractResponses {
-  const responses: ContractResponses = {};
-  for (const error of Object.values(errors)) {
-    responses[error.status] = STANDARD_ERROR_RESPONSE_SCHEMA;
-  }
-  return responses;
-}
-
-function assertNoResponseStatusConflicts(
-  current: ContractResponses,
-  next: ContractResponses,
-): void {
-  const currentStatuses = new Set(Object.keys(current));
-  const conflicts = Object.keys(next).filter((status) =>
-    currentStatuses.has(status),
-  );
-  if (conflicts.length) {
-    throw new Error(
-      `.errors() cannot declare status ${conflicts.join(", ")} because a response schema for that status already exists. Use .responses() without .errors() when you need a custom error response body.`,
-    );
-  }
-}
-
-function assertNoCatalogErrorStatusConflicts(
-  metadata: ContractMeta,
-  next: ContractResponses,
-): void {
-  const errors = metadata.errors;
-  if (typeof errors !== "object" || errors === null) return;
-
-  const errorStatuses = new Set(
-    Object.values(errors)
-      .map((error) =>
-        typeof error === "object" &&
-        error !== null &&
-        typeof (error as { status?: unknown }).status === "number"
-          ? String((error as { status: number }).status)
-          : undefined,
-      )
-      .filter((status): status is string => status !== undefined),
-  );
-  const conflicts = Object.keys(next).filter((status) =>
-    errorStatuses.has(status),
-  );
-  if (conflicts.length) {
-    throw new Error(
-      `.responses() cannot declare status ${conflicts.join(", ")} because that status is already declared by .errors(). Use .responses() without .errors() when you need a custom error response body.`,
-    );
-  }
-}
-
 /**
  * Feature-scoped factory for related HTTP contracts.
  *
@@ -195,13 +149,13 @@ export class ContractGroup<
     meta: TNewMeta,
   ): ContractGroup<
     TSharedResponses,
-    Omit<TSharedMeta, keyof TNewMeta> & TNewMeta,
+    OmitMetaKeys<TSharedMeta, keyof TNewMeta> & TNewMeta,
     TSharedHeaders,
     TPathPrefix
   > {
     return new ContractGroup({
       namespace: this._namespace,
-      meta: { ...this._meta, ...meta } as unknown as Omit<
+      meta: { ...this._meta, ...meta } as unknown as OmitMetaKeys<
         TSharedMeta,
         keyof TNewMeta
       > &
@@ -226,7 +180,7 @@ export class ContractGroup<
     TSharedHeaders,
     TPathPrefix
   > {
-    assertNoCatalogErrorStatusConflicts(this._meta, responseSchemas);
+    assertResponsesAvoidCatalogErrorStatuses(this._meta, responseSchemas);
     return new ContractGroup({
       namespace: this._namespace,
       meta: this._meta,
@@ -244,25 +198,36 @@ export class ContractGroup<
    * Declare shared route-owned application errors for contracts in this group.
    *
    * Catalog errors use Beignet's standard error envelope and remain separate
-   * from framework-owned errors.
+   * from framework-owned errors. Declarations merge with previously declared
+   * group errors, and contracts created from the group merge these shared
+   * errors with route-level `.errors()` declarations; later declarations win
+   * when the same catalog key is declared twice.
    */
   errors<TErrorDefs extends ContractErrorResponses>(
     errorDefs: TErrorDefs,
   ): ContractGroup<
     Omit<TSharedResponses, keyof ResponsesFromErrorDefinitions<TErrorDefs>> &
       ResponsesFromErrorDefinitions<TErrorDefs>,
-    Omit<TSharedMeta, "errors"> & { errors: TErrorDefs },
+    OmitMetaKeys<TSharedMeta, "errors"> & {
+      errors: MergedContractErrorResponses<TSharedMeta, TErrorDefs>;
+    },
     TSharedHeaders,
     TPathPrefix
   > {
     const errorResponses = responsesFromErrors(errorDefs);
-    assertNoResponseStatusConflicts(this._responses, errorResponses);
+    assertErrorsAvoidCustomResponseStatuses(
+      this._meta,
+      this._responses,
+      errorResponses,
+    );
     return new ContractGroup({
       namespace: this._namespace,
       meta: {
         ...this._meta,
-        errors: errorDefs,
-      } as Omit<TSharedMeta, "errors"> & { errors: TErrorDefs },
+        errors: mergeCatalogErrors(this._meta, errorDefs),
+      } as unknown as OmitMetaKeys<TSharedMeta, "errors"> & {
+        errors: MergedContractErrorResponses<TSharedMeta, TErrorDefs>;
+      },
       responses: { ...this._responses, ...errorResponses } as unknown as Omit<
         TSharedResponses,
         keyof ResponsesFromErrorDefinitions<TErrorDefs>
@@ -495,7 +460,7 @@ export class ContractGroup<
  *
  * @example
  * ```ts
- * const todos = createContractGroup()
+ * const todos = defineContractGroup()
  *   .namespace("todos")
  *   .prefix("/api/todos")
  *   .meta({ auth: "required" })
@@ -508,7 +473,7 @@ export class ContractGroup<
  *
  * @returns An empty immutable contract group.
  */
-export function createContractGroup(): ContractGroup<
+export function defineContractGroup(): ContractGroup<
   Record<never, never>,
   ContractMeta,
   null,

package/src/contracts/contract-like.ts

@@ -1,4 +1,4 @@
-import type { HttpContractConfig } from "./types";
+import type { HttpContractConfig } from "./types.js";
 
 /**
  * Contract input accepted by APIs that can unwrap builders.

package/src/contracts/index.ts

@@ -11,19 +11,22 @@ export type { StandardSchemaV1 } from "@standard-schema/spec";
 /**
  * Idempotency metadata types for contracts.
  */
-export type { IdempotencyMeta, IdempotencyScopeMode } from "../idempotency";
+export type {
+  IdempotencyMeta,
+  IdempotencyScopeMode,
+} from "../idempotency/index.js";
 /**
  * Contract builder exports.
  */
 export {
   ContractBuilder,
-  type CreateContractOptions,
-  createContract,
-} from "./contract-builder";
+  type DefineContractOptions,
+  defineContract,
+} from "./contract-builder.js";
 /**
  * Contract group exports.
  */
-export { ContractGroup, createContractGroup } from "./contract-group";
+export { ContractGroup, defineContractGroup } from "./contract-group.js";
 /**
  * Contract-like helper exports.
  */
@@ -31,11 +34,11 @@ export {
   type ContractLike,
   type ResolveContract,
   resolveContract,
-} from "./contract-like";
+} from "./contract-like.js";
 /**
  * OpenAPI operation metadata type.
  */
-export type { OpenAPIOperationMeta } from "./openapi-meta";
+export type { OpenAPIOperationMeta } from "./openapi-meta.js";
 /**
  * Path template parsing exports.
  */
@@ -43,11 +46,20 @@ export {
   type ParsedPathTemplate,
   type PathTemplateSegment,
   parsePathTemplate,
-} from "./path-template";
+} from "./path-template.js";
 /**
  * Rate limit metadata types for contracts.
  */
-export type { RateLimitMeta, RateLimitScope } from "./rate-limit";
+export type { RateLimitMeta, RateLimitScope } from "./rate-limit.js";
+/**
+ * Success status helpers shared by the server route binder and tooling.
+ */
+export {
+  getSuccess2xxStatuses,
+  type IsSingle2xx,
+  inferSoleSuccessStatus,
+  type Success2xxKeys,
+} from "./success-status.js";
 /**
  * Contract config and inference types.
  */
@@ -66,15 +78,16 @@ export type {
   InferHeaderSchemaOutput,
   InferInput,
   InferOutput,
+  MergedContractErrorResponses,
   ResponsesFromErrorDefinitions,
   StandardErrorResponseBody,
   StandardErrorResponseSchema,
   StandardSchema,
-} from "./types";
+} from "./types.js";
 export {
   BEIGNET_ERROR_OWNER_HEADER,
   BODY_HTTP_METHODS,
   getContractHeaderSchemas,
   methodSupportsRequestBody,
   STANDARD_ERROR_RESPONSE_SCHEMA,
-} from "./types";
+} from "./types.js";

package/src/contracts/openapi-meta.ts

@@ -1,6 +1,55 @@
 /**
  * OpenAPI operation-level metadata for HTTP contracts.
  */
+
+/**
+ * Inline OpenAPI schema metadata or a `$ref` to a schema component.
+ */
+export type OpenAPISchemaMeta = Record<string, unknown> | { $ref: string };
+
+/**
+ * OpenAPI media type metadata for request and response content entries.
+ */
+export type OpenAPIMediaTypeMeta = {
+  schema?: OpenAPISchemaMeta;
+  examples?: Record<
+    string,
+    {
+      summary?: string;
+      value?: unknown;
+    }
+  >;
+};
+
+/**
+ * OpenAPI request body metadata used to override generated JSON request bodies.
+ */
+export type OpenAPIRequestBodyMeta = {
+  required?: boolean;
+  description?: string;
+  content: Record<string, OpenAPIMediaTypeMeta>;
+};
+
+/**
+ * OpenAPI response metadata used to add or replace generated responses.
+ */
+export type OpenAPIResponseMeta = {
+  description: string;
+  content?: Record<string, OpenAPIMediaTypeMeta>;
+};
+
+/**
+ * OpenAPI operation parameter metadata used for custom parameters such as cookies.
+ */
+export type OpenAPIParameterMeta = {
+  name: string;
+  in: "path" | "query" | "header" | "cookie";
+  required?: boolean;
+  schema?: OpenAPISchemaMeta;
+  description?: string;
+  deprecated?: boolean;
+};
+
 export type OpenAPIOperationMeta = {
   /** Brief operation summary. */
   summary?: string;
@@ -19,4 +68,10 @@ export type OpenAPIOperationMeta = {
   operationId?: string;
   /** Per-operation security requirements. */
   security?: Array<Record<string, string[]>>;
+  /** Additional or replacement operation parameters. */
+  parameters?: OpenAPIParameterMeta[];
+  /** Replacement request body for non-JSON media such as multipart uploads. */
+  requestBody?: OpenAPIRequestBodyMeta;
+  /** Additional or replacement responses, useful for files and streams. */
+  responses?: Record<string, OpenAPIResponseMeta>;
 };

package/src/contracts/path-template.ts

@@ -38,7 +38,7 @@ const BRACKET_PARAM = new RegExp(`^\\[(${PARAM_NAME})\\]$`);
 function createPathTemplateError(path: string, segment: string): Error {
   return new Error(
     `Unsupported path template segment "${segment}" in "${path}". ` +
-      "Use single-segment params like :id or [id]. Catch-all and partial-segment params are not supported.",
+      "Use single-segment params like :id or [id]. Contract catch-all params such as [...path] and partial-segment params are not supported. Expose a platform catch-all route to the Beignet server, but keep individual contracts on concrete paths.",
   );
 }
 
@@ -68,7 +68,7 @@ function parsePathSegment(path: string, segment: string): PathTemplateSegment {
  * Parse a Beignet route path template.
  *
  * Paths must start with `/`. Dynamic segments may use `:id` or `[id]`.
- * Catch-all segments and partial dynamic segments are intentionally rejected.
+ * Contract catch-all segments and partial dynamic segments are intentionally rejected.
  */
 export function parsePathTemplate(path: string): ParsedPathTemplate {
   if (!path.startsWith("/")) {