@beignet/core 0.0.1 → 0.0.2

package/dist/contracts/contract-builder.js

@@ -32,8 +32,12 @@ function assertNoCatalogErrorStatusConflicts(metadata, next) {
     }
 }
 /**
- * Contract builder for constructing HTTP contracts in a fluent API style
- * Schemas are accessible via the .schema property for introspection
+ * Fluent builder for one HTTP contract.
+ *
+ * A contract describes the transport boundary for one endpoint: method, path,
+ * request schemas, response schemas, metadata, and route-owned catalog errors.
+ * Builder methods are immutable; each call returns a new builder with narrower
+ * types.
  */
 export class ContractBuilder {
     kind;
@@ -66,7 +70,10 @@ export class ContractBuilder {
         this._meta = config.metadata;
     }
     /**
-     * Access schemas for introspection
+     * Request and response schemas attached to this contract.
+     *
+     * Server adapters use these for validation. Client and frontend integrations
+     * use them for local validation and type inference.
      */
     get schema() {
         return {
@@ -78,32 +85,31 @@ export class ContractBuilder {
         };
     }
     /**
-     * Get response schemas for introspection
+     * Response schemas keyed by HTTP status code.
      */
     get responseSchemas() {
         return this._responses;
     }
     /**
-     * Get the URL path template
+     * URL path template for this contract.
      */
     get pathTemplate() {
         return this._path;
     }
     /**
-     * Get the URL path (alias for pathTemplate)
+     * URL path template alias.
      */
     get path() {
         return this._path;
     }
     /**
-     * Get contract metadata
+     * Metadata consumed by hooks, OpenAPI generation, and app conventions.
      */
     get metadata() {
         return this._meta;
     }
     /**
-     * Get the contract as an HttpContractConfig object
-     * Use this when passing to adapters that expect the plain config type
+     * Plain contract config consumed by framework internals and integrations.
      */
     get config() {
         return {
@@ -122,7 +128,10 @@ export class ContractBuilder {
         };
     }
     /**
-     * Set path parameters schema (chainable builder method)
+     * Attach a schema for dynamic path parameters.
+     *
+     * The schema validates parameters parsed from path templates such as
+     * `/posts/:id` or `/posts/[id]`.
      */
     pathParams(schema) {
         return new ContractBuilder({
@@ -141,7 +150,7 @@ export class ContractBuilder {
         });
     }
     /**
-     * Set query parameters schema (chainable builder method)
+     * Attach a schema for query parameters.
      */
     query(schema) {
         return new ContractBuilder({
@@ -160,8 +169,9 @@ export class ContractBuilder {
         });
     }
     /**
-     * Set request body schema (chainable builder method)
-     * Only available on POST, PUT, and PATCH contracts.
+     * Attach a schema for a JSON request body.
+     *
+     * This method is only available on POST, PUT, and PATCH contracts.
      */
     body(schema) {
         const self = this;
@@ -181,10 +191,11 @@ export class ContractBuilder {
         });
     }
     /**
-     * Add request header schema (chainable).
+     * Attach a request header schema.
      *
      * Multiple schemas are evaluated in declaration order and their parsed
-     * outputs are merged. This keeps group-level headers library-agnostic.
+     * outputs are merged. This lets a contract inherit shared group headers and
+     * still declare route-specific headers.
      */
     headers(schema) {
         const existingHeaders = this._headers
@@ -211,7 +222,12 @@ export class ContractBuilder {
         });
     }
     /**
-     * Add or replace response schemas by status code (chainable).
+     * Add or replace route-owned response schemas by status code.
+     *
+     * These schemas describe business responses returned by route handlers.
+     * Framework-owned errors such as request validation failures do not need to be
+     * declared here.
+     *
      * Use `null` for void/empty responses such as 204 No Content.
      */
     responses(responseSchemas) {
@@ -237,8 +253,9 @@ export class ContractBuilder {
     /**
      * 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.
+     * 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.
      */
     errors(errorDefs) {
         const errorResponses = responsesFromErrors(errorDefs);
@@ -265,7 +282,10 @@ export class ContractBuilder {
         });
     }
     /**
-     * Set or merge contract metadata (chainable builder method)
+     * Merge metadata into this contract.
+     *
+     * Hooks and tooling can read metadata for concerns such as auth, rate limits,
+     * idempotency, OpenAPI, or app-specific conventions.
      */
     meta(newMeta) {
         return new ContractBuilder({
@@ -287,7 +307,7 @@ export class ContractBuilder {
         });
     }
     /**
-     * Set or merge OpenAPI metadata for this operation (chainable)
+     * Merge OpenAPI operation metadata into this contract.
      */
     openapi(patch) {
         const existingOpenApi = this._meta.openapi ?? {};
@@ -314,7 +334,11 @@ export class ContractBuilder {
     }
 }
 /**
- * Create a new HTTP contract with the builder pattern.
+ * Create a new HTTP contract builder.
+ *
+ * Most apps prefer `createContractGroup().namespace(...).prefix(...)` for
+ * related feature contracts. Use this lower-level factory when a standalone
+ * contract is clearer.
  *
  * @example
  * ```ts
@@ -325,6 +349,9 @@ export class ContractBuilder {
  *   .pathParams(z.object({ id: z.string() }))
  *   .responses({ 200: TodoSchema });
  * ```
+ *
+ * @param options - HTTP method, path template, and optional contract name.
+ * @returns A fluent contract builder.
  */
 export function createContract(options) {
     parsePathTemplate(options.path);

package/dist/contracts/contract-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract-builder.js","sourceRoot":"","sources":["../../src/contracts/contract-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract-builder.js","sourceRoot":"","sources":["../../src/contracts/contract-builder.ts"],"names":[],"mappings":"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"}

package/dist/contracts/contract-group.d.ts

@@ -6,8 +6,11 @@ type NormalizedPrefix<T extends string> = T extends "" | "/" ? "" : TrimTrailing
 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>}`;
 /**
- * ContractGroup is a feature-scoped factory for creating related contracts
- * with shared configuration. Immutable — each method returns a new instance.
+ * Feature-scoped factory for related HTTP contracts.
+ *
+ * Contract groups let a feature share a namespace, path prefix, headers,
+ * responses, errors, and metadata across multiple endpoint contracts. The group
+ * is immutable: every configuration method returns a new group.
  */
 export declare class ContractGroup<TSharedResponses extends ContractResponses = Record<never, never>, TSharedMeta extends ContractMeta = ContractMeta, TSharedHeaders extends ContractHeaderSchemas = null, TPathPrefix extends string = ""> {
     private readonly _namespace;
@@ -23,61 +26,69 @@ export declare class ContractGroup<TSharedResponses extends ContractResponses =
         pathPrefix?: TPathPrefix;
     });
     /**
-     * Set the namespace for all contracts created from this group
+     * Set the namespace for contracts created from this group.
+     *
+     * The namespace prefixes contract names, not paths. Use `prefix(...)` for
+     * path composition.
      */
     namespace(ns: string): ContractGroup<TSharedResponses, TSharedMeta, TSharedHeaders, TPathPrefix>;
     /**
-     * Add a path prefix to all contracts created from this group.
+     * Add a path prefix to contracts created from this group.
      *
-     * Prefixes compose immutably, so `prefix("/api").prefix("/v1")`
-     * produces paths under `/api/v1`.
+     * 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>>;
     /**
-     * Set shared metadata for all contracts created from this group
+     * Merge shared metadata into contracts created from this group.
      */
     meta<TNewMeta extends ContractMeta>(meta: TNewMeta): ContractGroup<TSharedResponses, Omit<TSharedMeta, keyof TNewMeta> & TNewMeta, TSharedHeaders, TPathPrefix>;
     /**
-     * Set shared response schemas for all contracts created from this group.
-     * Typically used for shared error responses (e.g. 401, 403, 500).
+     * Add shared route-owned response schemas to contracts created from this group.
+     *
+     * Framework-owned responses, such as validation or auth hook failures, do not
+     * need to be declared here.
      */
     responses<TNewResponses extends ContractResponses>(responseSchemas: TNewResponses): ContractGroup<Omit<TSharedResponses, keyof TNewResponses> & TNewResponses, TSharedMeta, TSharedHeaders, TPathPrefix>;
     /**
-     * Set shared route-owned application errors for all contracts in the group.
+     * 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.
      */
     errors<TErrorDefs extends ContractErrorResponses>(errorDefs: TErrorDefs): ContractGroup<Omit<TSharedResponses, keyof ResponsesFromErrorDefinitions<TErrorDefs>> & ResponsesFromErrorDefinitions<TErrorDefs>, Omit<TSharedMeta, "errors"> & {
         errors: TErrorDefs;
     }, TSharedHeaders, TPathPrefix>;
     /**
-     * Add shared request header schema for all contracts created from this group.
+     * Add a shared request header schema to 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>;
     /**
-     * Create a GET contract
+     * Create a GET contract under this group.
      */
     get<const TPath extends string>(path: TPath, name?: string): ContractBuilder<"GET", null, null, null, TSharedHeaders, TSharedResponses, TSharedMeta, JoinPaths<TPathPrefix, TPath>>;
     /**
-     * Create a POST contract
+     * Create a POST contract under this group.
      */
     post<const TPath extends string>(path: TPath, name?: string): ContractBuilder<"POST", null, null, null, TSharedHeaders, TSharedResponses, TSharedMeta, JoinPaths<TPathPrefix, TPath>>;
     /**
-     * Create a PUT contract
+     * Create a PUT contract under this group.
      */
     put<const TPath extends string>(path: TPath, name?: string): ContractBuilder<"PUT", null, null, null, TSharedHeaders, TSharedResponses, TSharedMeta, JoinPaths<TPathPrefix, TPath>>;
     /**
-     * Create a PATCH contract
+     * Create a PATCH contract under this group.
      */
     patch<const TPath extends string>(path: TPath, name?: string): ContractBuilder<"PATCH", null, null, null, TSharedHeaders, TSharedResponses, TSharedMeta, JoinPaths<TPathPrefix, TPath>>;
     /**
-     * Create a DELETE contract
+     * Create a DELETE contract under this group.
      */
     delete<const TPath extends string>(path: TPath, name?: string): ContractBuilder<"DELETE", null, null, null, TSharedHeaders, TSharedResponses, TSharedMeta, JoinPaths<TPathPrefix, TPath>>;
     /**
-     * Create a HEAD contract
+     * Create a HEAD contract under this group.
      */
     head<const TPath extends string>(path: TPath, name?: string): ContractBuilder<"HEAD", null, null, null, TSharedHeaders, TSharedResponses, TSharedMeta, JoinPaths<TPathPrefix, TPath>>;
     /**
-     * Create a OPTIONS contract
+     * Create an OPTIONS contract under this group.
      */
     options<const TPath extends string>(path: TPath, name?: string): ContractBuilder<"OPTIONS", null, null, null, TSharedHeaders, TSharedResponses, TSharedMeta, JoinPaths<TPathPrefix, TPath>>;
     /**
@@ -86,7 +97,10 @@ export declare class ContractGroup<TSharedResponses extends ContractResponses =
     private createBuilder;
 }
 /**
- * Create a new ContractGroup for grouping related contracts with shared configuration.
+ * Create a new feature contract group.
+ *
+ * Start here for most feature HTTP surfaces, then add a namespace and path
+ * prefix before defining individual contracts.
  *
  * @example
  * ```ts
@@ -100,6 +114,8 @@ export declare class ContractGroup<TSharedResponses extends ContractResponses =
  *
  * const getTodo = todos.get("/:id")...
  * ```
+ *
+ * @returns An empty immutable contract group.
  */
 export declare function createContractGroup(): ContractGroup<Record<never, never>, ContractMeta, null, "">;
 export {};

package/dist/contracts/contract-group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-group.d.ts","sourceRoot":"","sources":["../../src/contracts/contract-group.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract-group.d.ts","sourceRoot":"","sources":["../../src/contracts/contract-group.ts"],"names":[],"mappings":"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"}

package/dist/contracts/contract-group.js

@@ -40,8 +40,11 @@ function assertNoCatalogErrorStatusConflicts(metadata, next) {
     }
 }
 /**
- * ContractGroup is a feature-scoped factory for creating related contracts
- * with shared configuration. Immutable — each method returns a new instance.
+ * Feature-scoped factory for related HTTP contracts.
+ *
+ * Contract groups let a feature share a namespace, path prefix, headers,
+ * responses, errors, and metadata across multiple endpoint contracts. The group
+ * is immutable: every configuration method returns a new group.
  */
 export class ContractGroup {
     _namespace;
@@ -57,7 +60,10 @@ export class ContractGroup {
         this._pathPrefix = state.pathPrefix ?? "";
     }
     /**
-     * Set the namespace for all contracts created from this group
+     * Set the namespace for contracts created from this group.
+     *
+     * The namespace prefixes contract names, not paths. Use `prefix(...)` for
+     * path composition.
      */
     namespace(ns) {
         return new ContractGroup({
@@ -69,10 +75,10 @@ export class ContractGroup {
         });
     }
     /**
-     * Add a path prefix to all contracts created from this group.
+     * Add a path prefix to contracts created from this group.
      *
-     * Prefixes compose immutably, so `prefix("/api").prefix("/v1")`
-     * produces paths under `/api/v1`.
+     * Prefixes compose immutably, so `prefix("/api").prefix("/v1")` produces
+     * paths under `/api/v1`.
      */
     prefix(pathPrefix) {
         parsePathTemplate(pathPrefix);
@@ -87,7 +93,7 @@ export class ContractGroup {
         });
     }
     /**
-     * Set shared metadata for all contracts created from this group
+     * Merge shared metadata into contracts created from this group.
      */
     meta(meta) {
         return new ContractGroup({
@@ -99,8 +105,10 @@ export class ContractGroup {
         });
     }
     /**
-     * Set shared response schemas for all contracts created from this group.
-     * Typically used for shared error responses (e.g. 401, 403, 500).
+     * Add shared route-owned response schemas to contracts created from this group.
+     *
+     * Framework-owned responses, such as validation or auth hook failures, do not
+     * need to be declared here.
      */
     responses(responseSchemas) {
         assertNoCatalogErrorStatusConflicts(this._meta, responseSchemas);
@@ -113,7 +121,10 @@ export class ContractGroup {
         });
     }
     /**
-     * Set shared route-owned application errors for all contracts in the group.
+     * 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.
      */
     errors(errorDefs) {
         const errorResponses = responsesFromErrors(errorDefs);
@@ -130,7 +141,7 @@ export class ContractGroup {
         });
     }
     /**
-     * Add shared request header schema for all contracts created from this group.
+     * Add a shared request header schema to contracts created from this group.
      */
     headers(schema) {
         const existingHeaders = this._headers
@@ -150,43 +161,43 @@ export class ContractGroup {
         });
     }
     /**
-     * Create a GET contract
+     * Create a GET contract under this group.
      */
     get(path, name) {
         return this.createBuilder("GET", path, name);
     }
     /**
-     * Create a POST contract
+     * Create a POST contract under this group.
      */
     post(path, name) {
         return this.createBuilder("POST", path, name);
     }
     /**
-     * Create a PUT contract
+     * Create a PUT contract under this group.
      */
     put(path, name) {
         return this.createBuilder("PUT", path, name);
     }
     /**
-     * Create a PATCH contract
+     * Create a PATCH contract under this group.
      */
     patch(path, name) {
         return this.createBuilder("PATCH", path, name);
     }
     /**
-     * Create a DELETE contract
+     * Create a DELETE contract under this group.
      */
     delete(path, name) {
         return this.createBuilder("DELETE", path, name);
     }
     /**
-     * Create a HEAD contract
+     * Create a HEAD contract under this group.
      */
     head(path, name) {
         return this.createBuilder("HEAD", path, name);
     }
     /**
-     * Create a OPTIONS contract
+     * Create an OPTIONS contract under this group.
      */
     options(path, name) {
         return this.createBuilder("OPTIONS", path, name);
@@ -219,7 +230,10 @@ export class ContractGroup {
     }
 }
 /**
- * Create a new ContractGroup for grouping related contracts with shared configuration.
+ * Create a new feature contract group.
+ *
+ * Start here for most feature HTTP surfaces, then add a namespace and path
+ * prefix before defining individual contracts.
  *
  * @example
  * ```ts
@@ -233,6 +247,8 @@ export class ContractGroup {
  *
  * const getTodo = todos.get("/:id")...
  * ```
+ *
+ * @returns An empty immutable contract group.
  */
 export function createContractGroup() {
     return new ContractGroup();

package/dist/contracts/contract-group.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract-group.js","sourceRoot":"","sources":["../../src/contracts/contract-group.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract-group.js","sourceRoot":"","sources":["../../src/contracts/contract-group.ts"],"names":[],"mappings":"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"}

package/dist/contracts/contract-like.d.ts

@@ -1,19 +1,19 @@
 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)
+ * Contract input accepted by APIs that can unwrap builders.
  */
 export type ContractLike = HttpContractConfig | {
     config: HttpContractConfig;
 };
 /**
- * Resolves a ContractLike to its underlying HttpContractConfig
+ * Resolve a contract-like type to its plain `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
+ * Resolve a contract builder or plain config to the underlying contract config.
+ *
  * @param c - The contract-like object to resolve
  * @returns The underlying HttpContractConfig
  */

package/dist/contracts/contract-like.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-like.d.ts","sourceRoot":"","sources":["../../src/contracts/contract-like.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG;IAAE,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC1D,CAAC,SAAS,kBAAkB,GAC1B,CAAC,GACD,KAAK,GACP,CAAC,SAAS,kBAAkB,GAC1B,CAAC,GACD,KAAK,CAAC;AAEZ;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,CAAC,EAAE,CAAC,GACH,eAAe,CAAC,CAAC,CAAC,CAEpB"}
+{"version":3,"file":"contract-like.d.ts","sourceRoot":"","sources":["../../src/contracts/contract-like.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG;IAAE,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC1D,CAAC,SAAS,kBAAkB,GAC1B,CAAC,GACD,KAAK,GACP,CAAC,SAAS,kBAAkB,GAC1B,CAAC,GACD,KAAK,CAAC;AAEZ;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,CAAC,EAAE,CAAC,GACH,eAAe,CAAC,CAAC,CAAC,CAEpB"}

package/dist/contracts/contract-like.js

@@ -1,5 +1,6 @@
 /**
- * Helper function to resolve a ContractLike to its underlying HttpContractConfig
+ * Resolve a contract builder or plain config to the underlying contract config.
+ *
  * @param c - The contract-like object to resolve
  * @returns The underlying HttpContractConfig
  */

package/dist/contracts/contract-like.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract-like.js","sourceRoot":"","sources":["../../src/contracts/contract-like.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,CAAI;IAEJ,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAuB,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"contract-like.js","sourceRoot":"","sources":["../../src/contracts/contract-like.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,CAAI;IAEJ,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAuB,CAAC;AAC9D,CAAC"}

package/dist/contracts/index.d.ts

@@ -3,13 +3,41 @@
  *
  * HTTP contract definitions and builders for Beignet.
  */
+/**
+ * Standard Schema type re-exported for contract authors.
+ */
 export type { StandardSchemaV1 } from "@standard-schema/spec";
+/**
+ * Idempotency metadata types for contracts.
+ */
+export type { IdempotencyMeta, IdempotencyScopeMode } from "../idempotency";
+/**
+ * Contract builder exports.
+ */
 export { ContractBuilder, type CreateContractOptions, createContract, } from "./contract-builder";
+/**
+ * Contract group exports.
+ */
 export { ContractGroup, createContractGroup } from "./contract-group";
+/**
+ * Contract-like helper exports.
+ */
 export { type ContractLike, type ResolveContract, resolveContract, } from "./contract-like";
+/**
+ * OpenAPI operation metadata type.
+ */
 export type { OpenAPIOperationMeta } from "./openapi-meta";
+/**
+ * Path template parsing exports.
+ */
 export { type ParsedPathTemplate, type PathTemplateSegment, parsePathTemplate, } from "./path-template";
+/**
+ * Rate limit metadata types for contracts.
+ */
 export type { RateLimitMeta, RateLimitScope } from "./rate-limit";
+/**
+ * Contract config and inference types.
+ */
 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";
 //# sourceMappingURL=index.d.ts.map

package/dist/contracts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EACV,WAAW,EACX,cAAc,EACd,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,sBAAsB,EACtB,uBAAuB,EACvB,UAAU,EACV,WAAW,EACX,6BAA6B,EAC7B,yBAAyB,EACzB,2BAA2B,EAC3B,cAAc,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC5E;;GAEG;AACH,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACtE;;GAEG;AACH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB;;GAEG;AACH,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D;;GAEG;AACH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB;;GAEG;AACH,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAClE;;GAEG;AACH,YAAY,EACV,WAAW,EACX,cAAc,EACd,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,sBAAsB,EACtB,uBAAuB,EACvB,UAAU,EACV,WAAW,EACX,6BAA6B,EAC7B,yBAAyB,EACzB,2BAA2B,EAC3B,cAAc,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,SAAS,CAAC"}