@beignet/core 0.0.1

package/src/contracts/contract-group.ts

@@ -0,0 +1,502 @@
+import { ContractBuilder } from "./contract-builder";
+import { parsePathTemplate } from "./path-template";
+import type {
+  ContractErrorResponses,
+  ContractHeaderSchemas,
+  ContractMeta,
+  ContractResponses,
+  HttpMethod,
+  ResponsesFromErrorDefinitions,
+  StandardSchema,
+} from "./types";
+import { STANDARD_ERROR_RESPONSE_SCHEMA } from "./types";
+import { generateContractName } from "./utils";
+
+type TrimLeadingSlash<T extends string> = T extends `/${infer Rest}`
+  ? TrimLeadingSlash<Rest>
+  : T;
+
+type TrimTrailingSlash<T extends string> = T extends "/"
+  ? ""
+  : T extends `${infer Rest}/`
+    ? TrimTrailingSlash<Rest>
+    : T;
+
+type NormalizedPrefix<T extends string> = T extends "" | "/"
+  ? ""
+  : TrimTrailingSlash<T>;
+
+type NormalizedChildPath<T extends string> = TrimTrailingSlash<
+  TrimLeadingSlash<T>
+>;
+
+type JoinPaths<TPrefix extends string, TPath extends string> = string extends
+  | TPrefix
+  | TPath
+  ? string
+  : NormalizedPrefix<TPrefix> extends ""
+    ? TPath
+    : NormalizedChildPath<TPath> extends ""
+      ? NormalizedPrefix<TPrefix>
+      : `${NormalizedPrefix<TPrefix>}/${NormalizedChildPath<TPath>}`;
+
+function joinPathPrefix(prefix: string, path: string): string {
+  const segments = [
+    ...prefix.split("/").filter(Boolean),
+    ...path.split("/").filter(Boolean),
+  ];
+
+  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.`,
+    );
+  }
+}
+
+/**
+ * ContractGroup is a feature-scoped factory for creating related contracts
+ * with shared configuration. Immutable — each method returns a new instance.
+ */
+export class ContractGroup<
+  TSharedResponses extends ContractResponses = Record<never, never>,
+  TSharedMeta extends ContractMeta = ContractMeta,
+  TSharedHeaders extends ContractHeaderSchemas = null,
+  TPathPrefix extends string = "",
+> {
+  private readonly _namespace: string;
+  private readonly _meta: TSharedMeta;
+  private readonly _responses: TSharedResponses;
+  private readonly _headers: TSharedHeaders;
+  private readonly _pathPrefix: TPathPrefix;
+
+  constructor(
+    state: {
+      namespace?: string;
+      meta?: TSharedMeta;
+      responses?: TSharedResponses;
+      headers?: TSharedHeaders;
+      pathPrefix?: TPathPrefix;
+    } = {} as {
+      namespace?: string;
+      meta?: TSharedMeta;
+      responses?: TSharedResponses;
+      headers?: TSharedHeaders;
+      pathPrefix?: TPathPrefix;
+    },
+  ) {
+    this._namespace = state.namespace ?? "";
+    this._meta = state.meta ?? ({} as TSharedMeta);
+    this._responses = state.responses ?? ({} as TSharedResponses);
+    this._headers = state.headers ?? (null as TSharedHeaders);
+    this._pathPrefix = state.pathPrefix ?? ("" as TPathPrefix);
+  }
+
+  /**
+   * Set the namespace for all contracts created from this group
+   */
+  namespace(
+    ns: string,
+  ): ContractGroup<TSharedResponses, TSharedMeta, TSharedHeaders, TPathPrefix> {
+    return new ContractGroup({
+      namespace: ns,
+      meta: this._meta,
+      responses: this._responses,
+      headers: this._headers,
+      pathPrefix: this._pathPrefix,
+    });
+  }
+
+  /**
+   * Add a path prefix to all contracts created from this group.
+   *
+   * Prefixes compose immutably, so `prefix("/api").prefix("/v1")`
+   * produces paths under `/api/v1`.
+   */
+  prefix<const TNewPrefix extends string>(
+    pathPrefix: TNewPrefix,
+  ): ContractGroup<
+    TSharedResponses,
+    TSharedMeta,
+    TSharedHeaders,
+    JoinPaths<TPathPrefix, TNewPrefix>
+  > {
+    parsePathTemplate(pathPrefix);
+    const nextPrefix = joinPathPrefix(this._pathPrefix, pathPrefix);
+    const normalizedPrefix = nextPrefix === "/" ? "" : nextPrefix;
+
+    return new ContractGroup({
+      namespace: this._namespace,
+      meta: this._meta,
+      responses: this._responses,
+      headers: this._headers,
+      pathPrefix: normalizedPrefix as JoinPaths<TPathPrefix, TNewPrefix>,
+    });
+  }
+
+  /**
+   * Set shared metadata for all contracts created from this group
+   */
+  meta<TNewMeta extends ContractMeta>(
+    meta: TNewMeta,
+  ): ContractGroup<
+    TSharedResponses,
+    Omit<TSharedMeta, keyof TNewMeta> & TNewMeta,
+    TSharedHeaders,
+    TPathPrefix
+  > {
+    return new ContractGroup({
+      namespace: this._namespace,
+      meta: { ...this._meta, ...meta } as unknown as Omit<
+        TSharedMeta,
+        keyof TNewMeta
+      > &
+        TNewMeta,
+      responses: this._responses,
+      headers: this._headers,
+      pathPrefix: this._pathPrefix,
+    });
+  }
+
+  /**
+   * Set shared response schemas for all contracts created from this group.
+   * Typically used for shared error responses (e.g. 401, 403, 500).
+   */
+  responses<TNewResponses extends ContractResponses>(
+    responseSchemas: TNewResponses,
+  ): ContractGroup<
+    Omit<TSharedResponses, keyof TNewResponses> & TNewResponses,
+    TSharedMeta,
+    TSharedHeaders,
+    TPathPrefix
+  > {
+    assertNoCatalogErrorStatusConflicts(this._meta, responseSchemas);
+    return new ContractGroup({
+      namespace: this._namespace,
+      meta: this._meta,
+      responses: { ...this._responses, ...responseSchemas } as unknown as Omit<
+        TSharedResponses,
+        keyof TNewResponses
+      > &
+        TNewResponses,
+      headers: this._headers,
+      pathPrefix: this._pathPrefix,
+    });
+  }
+
+  /**
+   * Set shared route-owned application errors for all contracts in the group.
+   */
+  errors<TErrorDefs extends ContractErrorResponses>(
+    errorDefs: TErrorDefs,
+  ): ContractGroup<
+    Omit<TSharedResponses, keyof ResponsesFromErrorDefinitions<TErrorDefs>> &
+      ResponsesFromErrorDefinitions<TErrorDefs>,
+    Omit<TSharedMeta, "errors"> & { errors: TErrorDefs },
+    TSharedHeaders,
+    TPathPrefix
+  > {
+    const errorResponses = responsesFromErrors(errorDefs);
+    assertNoResponseStatusConflicts(this._responses, errorResponses);
+    return new ContractGroup({
+      namespace: this._namespace,
+      meta: {
+        ...this._meta,
+        errors: errorDefs,
+      } as Omit<TSharedMeta, "errors"> & { errors: TErrorDefs },
+      responses: { ...this._responses, ...errorResponses } as unknown as Omit<
+        TSharedResponses,
+        keyof ResponsesFromErrorDefinitions<TErrorDefs>
+      > &
+        ResponsesFromErrorDefinitions<TErrorDefs>,
+      headers: this._headers,
+      pathPrefix: this._pathPrefix,
+    });
+  }
+
+  /**
+   * Add shared request header schema for all contracts created from this group.
+   */
+  headers<TNewHeaders extends StandardSchema>(
+    schema: TNewHeaders,
+  ): ContractGroup<
+    TSharedResponses,
+    TSharedMeta,
+    TSharedHeaders extends readonly StandardSchema[]
+      ? readonly [...TSharedHeaders, TNewHeaders]
+      : TSharedHeaders extends StandardSchema
+        ? readonly [TSharedHeaders, TNewHeaders]
+        : readonly [TNewHeaders],
+    TPathPrefix
+  > {
+    const existingHeaders = this._headers
+      ? Array.isArray(this._headers)
+        ? this._headers
+        : [this._headers]
+      : [];
+
+    return new ContractGroup({
+      namespace: this._namespace,
+      meta: this._meta,
+      responses: this._responses,
+      headers: [
+        ...existingHeaders,
+        schema,
+      ] as unknown as TSharedHeaders extends readonly StandardSchema[]
+        ? readonly [...TSharedHeaders, TNewHeaders]
+        : TSharedHeaders extends StandardSchema
+          ? readonly [TSharedHeaders, TNewHeaders]
+          : readonly [TNewHeaders],
+      pathPrefix: this._pathPrefix,
+    });
+  }
+
+  /**
+   * Create a GET contract
+   */
+  get<const TPath extends string>(
+    path: TPath,
+    name?: string,
+  ): ContractBuilder<
+    "GET",
+    null,
+    null,
+    null,
+    TSharedHeaders,
+    TSharedResponses,
+    TSharedMeta,
+    JoinPaths<TPathPrefix, TPath>
+  > {
+    return this.createBuilder("GET", path, name);
+  }
+
+  /**
+   * Create a POST contract
+   */
+  post<const TPath extends string>(
+    path: TPath,
+    name?: string,
+  ): ContractBuilder<
+    "POST",
+    null,
+    null,
+    null,
+    TSharedHeaders,
+    TSharedResponses,
+    TSharedMeta,
+    JoinPaths<TPathPrefix, TPath>
+  > {
+    return this.createBuilder("POST", path, name);
+  }
+
+  /**
+   * Create a PUT contract
+   */
+  put<const TPath extends string>(
+    path: TPath,
+    name?: string,
+  ): ContractBuilder<
+    "PUT",
+    null,
+    null,
+    null,
+    TSharedHeaders,
+    TSharedResponses,
+    TSharedMeta,
+    JoinPaths<TPathPrefix, TPath>
+  > {
+    return this.createBuilder("PUT", path, name);
+  }
+
+  /**
+   * Create a PATCH contract
+   */
+  patch<const TPath extends string>(
+    path: TPath,
+    name?: string,
+  ): ContractBuilder<
+    "PATCH",
+    null,
+    null,
+    null,
+    TSharedHeaders,
+    TSharedResponses,
+    TSharedMeta,
+    JoinPaths<TPathPrefix, TPath>
+  > {
+    return this.createBuilder("PATCH", path, name);
+  }
+
+  /**
+   * Create a DELETE contract
+   */
+  delete<const TPath extends string>(
+    path: TPath,
+    name?: string,
+  ): ContractBuilder<
+    "DELETE",
+    null,
+    null,
+    null,
+    TSharedHeaders,
+    TSharedResponses,
+    TSharedMeta,
+    JoinPaths<TPathPrefix, TPath>
+  > {
+    return this.createBuilder("DELETE", path, name);
+  }
+
+  /**
+   * Create a HEAD contract
+   */
+  head<const TPath extends string>(
+    path: TPath,
+    name?: string,
+  ): ContractBuilder<
+    "HEAD",
+    null,
+    null,
+    null,
+    TSharedHeaders,
+    TSharedResponses,
+    TSharedMeta,
+    JoinPaths<TPathPrefix, TPath>
+  > {
+    return this.createBuilder("HEAD", path, name);
+  }
+
+  /**
+   * Create a OPTIONS contract
+   */
+  options<const TPath extends string>(
+    path: TPath,
+    name?: string,
+  ): ContractBuilder<
+    "OPTIONS",
+    null,
+    null,
+    null,
+    TSharedHeaders,
+    TSharedResponses,
+    TSharedMeta,
+    JoinPaths<TPathPrefix, TPath>
+  > {
+    return this.createBuilder("OPTIONS", path, name);
+  }
+
+  /**
+   * Internal helper to create a contract builder with shared config
+   */
+  private createBuilder<TMethod extends HttpMethod, const TPath extends string>(
+    method: TMethod,
+    path: TPath,
+    name?: string,
+  ): ContractBuilder<
+    TMethod,
+    null,
+    null,
+    null,
+    TSharedHeaders,
+    TSharedResponses,
+    TSharedMeta,
+    JoinPaths<TPathPrefix, TPath>
+  > {
+    parsePathTemplate(path);
+    const fullPath = (
+      this._pathPrefix ? joinPathPrefix(this._pathPrefix, path) : path
+    ) as JoinPaths<TPathPrefix, TPath>;
+    parsePathTemplate(fullPath);
+    const contractName = name || generateContractName(method, fullPath);
+    const fullName = this._namespace
+      ? `${this._namespace}.${contractName}`
+      : contractName;
+
+    return new ContractBuilder({
+      kind: "http",
+      name: fullName,
+      namespace: this._namespace || undefined,
+      localName: contractName,
+      method,
+      path: fullPath,
+      pathParams: null,
+      query: null,
+      headers: this._headers,
+      body: null,
+      responses: { ...this._responses } as unknown as TSharedResponses,
+      metadata: { ...this._meta } as unknown as TSharedMeta,
+    });
+  }
+}
+
+/**
+ * Create a new ContractGroup for grouping related contracts with shared configuration.
+ *
+ * @example
+ * ```ts
+ * const todos = createContractGroup()
+ *   .namespace("todos")
+ *   .prefix("/api/todos")
+ *   .meta({ auth: "required" })
+ *   .responses({
+ *     401: z.object({ message: z.literal("Unauthorized") }),
+ *   });
+ *
+ * const getTodo = todos.get("/:id")...
+ * ```
+ */
+export function createContractGroup(): ContractGroup<
+  Record<never, never>,
+  ContractMeta,
+  null,
+  ""
+> {
+  return new ContractGroup();
+}

package/src/contracts/contract-like.ts

@@ -0,0 +1,29 @@
+import type { HttpContractConfig } from "./types";
+
+/**
+ * A type that represents either a raw HttpContractConfig
+ * or a contract-like object with a .config property (e.g., ContractBuilder)
+ */
+export type ContractLike = HttpContractConfig | { config: HttpContractConfig };
+
+/**
+ * Resolves a ContractLike to its underlying HttpContractConfig
+ */
+export type ResolveContract<T> = T extends { config: infer C }
+  ? C extends HttpContractConfig
+    ? C
+    : never
+  : T extends HttpContractConfig
+    ? T
+    : never;
+
+/**
+ * Helper function to resolve a ContractLike to its underlying HttpContractConfig
+ * @param c - The contract-like object to resolve
+ * @returns The underlying HttpContractConfig
+ */
+export function resolveContract<T extends ContractLike>(
+  c: T,
+): ResolveContract<T> {
+  return ("config" in c ? c.config : c) as ResolveContract<T>;
+}

package/src/contracts/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @beignet/core/contracts
+ *
+ * HTTP contract definitions and builders for Beignet.
+ */
+
+export type { StandardSchemaV1 } from "@standard-schema/spec";
+
+export {
+  ContractBuilder,
+  type CreateContractOptions,
+  createContract,
+} from "./contract-builder";
+export { ContractGroup, createContractGroup } from "./contract-group";
+export {
+  type ContractLike,
+  type ResolveContract,
+  resolveContract,
+} from "./contract-like";
+export type { OpenAPIOperationMeta } from "./openapi-meta";
+export {
+  type ParsedPathTemplate,
+  type PathTemplateSegment,
+  parsePathTemplate,
+} from "./path-template";
+export type { RateLimitMeta, RateLimitScope } from "./rate-limit";
+export type {
+  AnyContract,
+  BodyHttpMethod,
+  ContractErrorDefinition,
+  ContractErrorResponses,
+  ContractHeaderSchemas,
+  ContractMeta,
+  ContractResponseSchema,
+  ContractResponses,
+  HttpContractConfig,
+  HttpMethod,
+  InferHeaderSchemaInput,
+  InferHeaderSchemaOutput,
+  InferInput,
+  InferOutput,
+  ResponsesFromErrorDefinitions,
+  StandardErrorResponseBody,
+  StandardErrorResponseSchema,
+  StandardSchema,
+} from "./types";
+export {
+  BEIGNET_ERROR_OWNER_HEADER,
+  BODY_HTTP_METHODS,
+  getContractHeaderSchemas,
+  methodSupportsRequestBody,
+  STANDARD_ERROR_RESPONSE_SCHEMA,
+} from "./types";

package/src/contracts/openapi-meta.ts

@@ -0,0 +1,22 @@
+/**
+ * OpenAPI operation-level metadata for HTTP contracts
+ */
+export type OpenAPIOperationMeta = {
+  /** A brief summary of the operation */
+  summary?: string;
+  /** A detailed description of the operation */
+  description?: string;
+  /** Tags for grouping operations */
+  tags?: string[];
+  /** Marks the operation as deprecated */
+  deprecated?: boolean;
+  /** External documentation reference */
+  externalDocs?: {
+    description?: string;
+    url: string;
+  };
+  /** Override for operationId (default is contract.name) */
+  operationId?: string;
+  /** Per-operation security requirements */
+  security?: Array<Record<string, string[]>>;
+};

package/src/contracts/path-template.ts

@@ -0,0 +1,91 @@
+export type PathTemplateSegment =
+  | { kind: "static"; value: string }
+  | { kind: "dynamic"; name: string; raw: string };
+
+export interface ParsedPathTemplate {
+  keys: string[];
+  segments: PathTemplateSegment[];
+  normalizedPath: string;
+  shapeKey: string;
+  openApiPath: string;
+}
+
+const PARAM_NAME = "[A-Za-z0-9_-]+";
+const COLON_PARAM = new RegExp(`^:(${PARAM_NAME})$`);
+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.",
+  );
+}
+
+function parsePathSegment(path: string, segment: string): PathTemplateSegment {
+  const colonMatch = segment.match(COLON_PARAM);
+  if (colonMatch) {
+    return { kind: "dynamic", name: colonMatch[1], raw: segment };
+  }
+
+  const bracketMatch = segment.match(BRACKET_PARAM);
+  if (bracketMatch) {
+    return { kind: "dynamic", name: bracketMatch[1], raw: segment };
+  }
+
+  if (
+    segment.startsWith(":") ||
+    segment.startsWith("[") ||
+    segment.endsWith("]")
+  ) {
+    throw createPathTemplateError(path, segment);
+  }
+
+  return { kind: "static", value: segment };
+}
+
+export function parsePathTemplate(path: string): ParsedPathTemplate {
+  if (!path.startsWith("/")) {
+    throw new Error(
+      `Invalid path template "${path}". Paths must start with "/".`,
+    );
+  }
+
+  const segments = path
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => parsePathSegment(path, segment));
+
+  const keys = segments
+    .filter(
+      (segment): segment is Extract<PathTemplateSegment, { kind: "dynamic" }> =>
+        segment.kind === "dynamic",
+    )
+    .map((segment) => segment.name);
+
+  const duplicateKeys = keys.filter(
+    (key, index) => keys.indexOf(key) !== index,
+  );
+  if (duplicateKeys.length) {
+    throw new Error(
+      `Invalid path template "${path}". Path parameter names must be unique; duplicate parameter "${duplicateKeys[0]}" was found.`,
+    );
+  }
+
+  const normalizedPath = `/${segments
+    .map((segment) =>
+      segment.kind === "static" ? segment.value : `:${segment.name}`,
+    )
+    .join("/")}`;
+
+  const shapeKey = `/${segments
+    .map((segment) => (segment.kind === "static" ? segment.value : ":"))
+    .join("/")}`;
+
+  const openApiPath = `/${segments
+    .map((segment) =>
+      segment.kind === "static" ? segment.value : `{${segment.name}}`,
+    )
+    .join("/")}`;
+
+  return { keys, segments, normalizedPath, shapeKey, openApiPath };
+}