@beignet/core 0.0.1

package/src/contracts/contract-builder.ts

@@ -0,0 +1,583 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { OpenAPIOperationMeta } from "./openapi-meta";
+import { parsePathTemplate } from "./path-template";
+import type {
+  BodyHttpMethod,
+  ContractErrorResponses,
+  ContractHeaderSchemas,
+  ContractMeta,
+  ContractResponses,
+  HttpContractConfig,
+  HttpMethod,
+  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.`,
+    );
+  }
+}
+
+/**
+ * Contract builder for constructing HTTP contracts in a fluent API style
+ * Schemas are accessible via the .schema property for introspection
+ */
+export class ContractBuilder<
+  TMethod extends HttpMethod,
+  TPathParams extends StandardSchema | null,
+  TQuery extends StandardSchema | null,
+  TBody extends StandardSchema | null,
+  THeaders extends ContractHeaderSchemas,
+  TResponses extends ContractResponses,
+  TMeta extends ContractMeta,
+  TPath extends string = string,
+> {
+  readonly kind: "http";
+  readonly name: string;
+  readonly namespace?: string;
+  readonly localName: string;
+  readonly method: TMethod;
+  private readonly _path: TPath;
+  private readonly _pathParams: TPathParams;
+  private readonly _query: TQuery;
+  private readonly _body: TBody;
+  private readonly _headers: THeaders;
+  private readonly _responses: TResponses;
+  private readonly _meta: TMeta;
+
+  constructor(
+    config: HttpContractConfig<
+      TMethod,
+      TPathParams,
+      TQuery,
+      TBody,
+      TResponses,
+      TMeta,
+      TPath,
+      THeaders
+    >,
+  ) {
+    if (config.body && !methodSupportsRequestBody(config.method)) {
+      throw new Error(
+        `Request bodies are not supported for ${config.method} contracts. Use POST, PUT, or PATCH for contract request bodies.`,
+      );
+    }
+    this.kind = config.kind;
+    this.name = config.name;
+    this.namespace = config.namespace;
+    this.localName = config.localName ?? config.name;
+    this.method = config.method;
+    this._path = config.path;
+    this._pathParams = config.pathParams;
+    this._query = config.query;
+    this._body = config.body;
+    this._headers = config.headers ?? (null as THeaders);
+    this._responses = config.responses;
+    this._meta = config.metadata;
+  }
+
+  /**
+   * Access schemas for introspection
+   */
+  get schema() {
+    return {
+      pathParams: this._pathParams,
+      query: this._query,
+      headers: this._headers,
+      body: this._body,
+      responses: this._responses,
+    };
+  }
+
+  /**
+   * Get response schemas for introspection
+   */
+  get responseSchemas(): TResponses {
+    return this._responses;
+  }
+
+  /**
+   * Get the URL path template
+   */
+  get pathTemplate(): TPath {
+    return this._path;
+  }
+
+  /**
+   * Get the URL path (alias for pathTemplate)
+   */
+  get path(): TPath {
+    return this._path;
+  }
+
+  /**
+   * Get contract metadata
+   */
+  get metadata(): TMeta {
+    return this._meta;
+  }
+
+  /**
+   * Get the contract as an HttpContractConfig object
+   * Use this when passing to adapters that expect the plain config type
+   */
+  get config(): HttpContractConfig<
+    TMethod,
+    TPathParams,
+    TQuery,
+    TBody,
+    TResponses,
+    TMeta,
+    TPath,
+    THeaders
+  > {
+    return {
+      kind: this.kind,
+      name: this.name,
+      namespace: this.namespace,
+      localName: this.localName,
+      method: this.method,
+      path: this._path,
+      pathParams: this._pathParams,
+      query: this._query,
+      headers: this._headers,
+      body: this._body,
+      responses: this._responses,
+      metadata: this._meta,
+    };
+  }
+
+  /**
+   * Set path parameters schema (chainable builder method)
+   */
+  pathParams<TNewPathParams extends StandardSchemaV1>(
+    schema: TNewPathParams,
+  ): ContractBuilder<
+    TMethod,
+    TNewPathParams,
+    TQuery,
+    TBody,
+    THeaders,
+    TResponses,
+    TMeta,
+    TPath
+  > {
+    return new ContractBuilder({
+      kind: this.kind,
+      name: this.name,
+      namespace: this.namespace,
+      localName: this.localName,
+      method: this.method,
+      path: this._path,
+      pathParams: schema as unknown as TNewPathParams,
+      query: this._query,
+      headers: this._headers,
+      body: this._body,
+      responses: this._responses,
+      metadata: this._meta,
+    });
+  }
+
+  /**
+   * Set query parameters schema (chainable builder method)
+   */
+  query<TNewQuery extends StandardSchemaV1>(
+    schema: TNewQuery,
+  ): ContractBuilder<
+    TMethod,
+    TPathParams,
+    TNewQuery,
+    TBody,
+    THeaders,
+    TResponses,
+    TMeta,
+    TPath
+  > {
+    return new ContractBuilder({
+      kind: this.kind,
+      name: this.name,
+      namespace: this.namespace,
+      localName: this.localName,
+      method: this.method,
+      path: this._path,
+      pathParams: this._pathParams,
+      query: schema as unknown as TNewQuery,
+      headers: this._headers,
+      body: this._body,
+      responses: this._responses,
+      metadata: this._meta,
+    });
+  }
+
+  /**
+   * Set request body schema (chainable builder method)
+   * Only available on POST, PUT, and PATCH contracts.
+   */
+  body<TNewBody extends StandardSchemaV1>(
+    this: ContractBuilder<
+      BodyHttpMethod,
+      StandardSchema | null,
+      StandardSchema | null,
+      StandardSchema | null,
+      ContractHeaderSchemas,
+      ContractResponses,
+      ContractMeta,
+      TPath
+    >,
+    schema: TNewBody,
+  ): ContractBuilder<
+    TMethod,
+    TPathParams,
+    TQuery,
+    TNewBody,
+    THeaders,
+    TResponses,
+    TMeta,
+    TPath
+  > {
+    const self = this as unknown as ContractBuilder<
+      TMethod,
+      TPathParams,
+      TQuery,
+      TBody,
+      THeaders,
+      TResponses,
+      TMeta,
+      TPath
+    >;
+    return new ContractBuilder({
+      kind: self.kind,
+      name: self.name,
+      namespace: self.namespace,
+      localName: self.localName,
+      method: self.method,
+      path: self._path,
+      pathParams: self._pathParams,
+      query: self._query,
+      headers: self._headers,
+      body: schema as unknown as TNewBody,
+      responses: self._responses,
+      metadata: self._meta,
+    });
+  }
+
+  /**
+   * Add request header schema (chainable).
+   *
+   * Multiple schemas are evaluated in declaration order and their parsed
+   * outputs are merged. This keeps group-level headers library-agnostic.
+   */
+  headers<TNewHeaders extends StandardSchemaV1>(
+    schema: TNewHeaders,
+  ): ContractBuilder<
+    TMethod,
+    TPathParams,
+    TQuery,
+    TBody,
+    THeaders extends readonly StandardSchema[]
+      ? readonly [...THeaders, TNewHeaders]
+      : THeaders extends StandardSchema
+        ? readonly [THeaders, TNewHeaders]
+        : readonly [TNewHeaders],
+    TResponses,
+    TMeta,
+    TPath
+  > {
+    const existingHeaders = this._headers
+      ? Array.isArray(this._headers)
+        ? this._headers
+        : [this._headers]
+      : [];
+
+    return new ContractBuilder({
+      kind: this.kind,
+      name: this.name,
+      namespace: this.namespace,
+      localName: this.localName,
+      method: this.method,
+      path: this._path,
+      pathParams: this._pathParams,
+      query: this._query,
+      headers: [
+        ...existingHeaders,
+        schema,
+      ] as unknown as THeaders extends readonly StandardSchema[]
+        ? readonly [...THeaders, TNewHeaders]
+        : THeaders extends StandardSchema
+          ? readonly [THeaders, TNewHeaders]
+          : readonly [TNewHeaders],
+      body: this._body,
+      responses: this._responses,
+      metadata: this._meta,
+    });
+  }
+
+  /**
+   * Add or replace response schemas by status code (chainable).
+   * Use `null` for void/empty responses such as 204 No Content.
+   */
+  responses<TNewResponses extends ContractResponses>(
+    responseSchemas: TNewResponses,
+  ): ContractBuilder<
+    TMethod,
+    TPathParams,
+    TQuery,
+    TBody,
+    THeaders,
+    Omit<TResponses, keyof TNewResponses> & TNewResponses,
+    TMeta,
+    TPath
+  > {
+    assertNoCatalogErrorStatusConflicts(this._meta, responseSchemas);
+    return new ContractBuilder({
+      kind: this.kind,
+      name: this.name,
+      namespace: this.namespace,
+      localName: this.localName,
+      method: this.method,
+      path: this._path,
+      pathParams: this._pathParams,
+      query: this._query,
+      headers: this._headers,
+      body: this._body,
+      responses: {
+        ...this._responses,
+        ...responseSchemas,
+      } as unknown as Omit<TResponses, keyof TNewResponses> & TNewResponses,
+      metadata: this._meta,
+    });
+  }
+
+  /**
+   * Declare route-owned application errors from an error catalog.
+   *
+   * Catalog errors use Beignet's standard error response envelope. Use
+   * `.responses()` when a route needs a custom error response body.
+   */
+  errors<TErrorDefs extends ContractErrorResponses>(
+    errorDefs: TErrorDefs,
+  ): ContractBuilder<
+    TMethod,
+    TPathParams,
+    TQuery,
+    TBody,
+    THeaders,
+    Omit<TResponses, keyof ResponsesFromErrorDefinitions<TErrorDefs>> &
+      ResponsesFromErrorDefinitions<TErrorDefs>,
+    Omit<TMeta, "errors"> & { errors: TErrorDefs },
+    TPath
+  > {
+    const errorResponses = responsesFromErrors(errorDefs);
+    assertNoResponseStatusConflicts(this._responses, errorResponses);
+    return new ContractBuilder({
+      kind: this.kind,
+      name: this.name,
+      namespace: this.namespace,
+      localName: this.localName,
+      method: this.method,
+      path: this._path,
+      pathParams: this._pathParams,
+      query: this._query,
+      headers: this._headers,
+      body: this._body,
+      responses: {
+        ...this._responses,
+        ...errorResponses,
+      } as unknown as Omit<
+        TResponses,
+        keyof ResponsesFromErrorDefinitions<TErrorDefs>
+      > &
+        ResponsesFromErrorDefinitions<TErrorDefs>,
+      metadata: {
+        ...this._meta,
+        errors: errorDefs,
+      } as Omit<TMeta, "errors"> & { errors: TErrorDefs },
+    });
+  }
+
+  /**
+   * Set or merge contract metadata (chainable builder method)
+   */
+  meta<TNewMeta extends ContractMeta>(
+    newMeta: TNewMeta,
+  ): ContractBuilder<
+    TMethod,
+    TPathParams,
+    TQuery,
+    TBody,
+    THeaders,
+    TResponses,
+    Omit<TMeta, keyof TNewMeta> & TNewMeta,
+    TPath
+  > {
+    return new ContractBuilder({
+      kind: this.kind,
+      name: this.name,
+      namespace: this.namespace,
+      localName: this.localName,
+      method: this.method,
+      path: this._path,
+      pathParams: this._pathParams,
+      query: this._query,
+      headers: this._headers,
+      body: this._body,
+      responses: this._responses,
+      metadata: {
+        ...this._meta,
+        ...newMeta,
+      } as unknown as Omit<TMeta, keyof TNewMeta> & TNewMeta,
+    });
+  }
+
+  /**
+   * Set or merge OpenAPI metadata for this operation (chainable)
+   */
+  openapi(
+    patch: Partial<OpenAPIOperationMeta>,
+  ): ContractBuilder<
+    TMethod,
+    TPathParams,
+    TQuery,
+    TBody,
+    THeaders,
+    TResponses,
+    TMeta,
+    TPath
+  > {
+    const existingOpenApi = this._meta.openapi ?? {};
+    return new ContractBuilder({
+      kind: this.kind,
+      name: this.name,
+      namespace: this.namespace,
+      localName: this.localName,
+      method: this.method,
+      path: this._path,
+      pathParams: this._pathParams,
+      query: this._query,
+      headers: this._headers,
+      body: this._body,
+      responses: this._responses,
+      metadata: {
+        ...this._meta,
+        openapi: {
+          ...existingOpenApi,
+          ...patch,
+        },
+      } as TMeta,
+    });
+  }
+}
+
+/**
+ * Options for creating a contract with the factory function
+ */
+export type CreateContractOptions<
+  TMethod extends HttpMethod = HttpMethod,
+  TPath extends string = string,
+> = {
+  /** HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) */
+  method: TMethod;
+  /** URL path template (e.g., "/api/users/:id") */
+  path: TPath;
+  /** Optional contract name (auto-generated from method + path if not provided) */
+  name?: string;
+};
+
+/**
+ * Create a new HTTP contract with the builder pattern.
+ *
+ * @example
+ * ```ts
+ * const getTodo = createContract({
+ *   method: "GET",
+ *   path: "/api/todos/:id",
+ * })
+ *   .pathParams(z.object({ id: z.string() }))
+ *   .responses({ 200: TodoSchema });
+ * ```
+ */
+export function createContract<
+  TMethod extends HttpMethod,
+  const TPath extends string,
+>(
+  options: CreateContractOptions<TMethod, TPath>,
+): ContractBuilder<
+  TMethod,
+  null,
+  null,
+  null,
+  null,
+  Record<never, never>,
+  ContractMeta,
+  TPath
+> {
+  parsePathTemplate(options.path);
+  const name =
+    options.name || generateContractName(options.method, options.path);
+  return new ContractBuilder({
+    kind: "http",
+    name,
+    localName: name,
+    method: options.method,
+    path: options.path,
+    pathParams: null,
+    query: null,
+    headers: null,
+    body: null,
+    responses: {},
+    metadata: {},
+  });
+}