@beignet/core 0.0.3 → 0.0.4

package/src/client/client.ts

@@ -10,8 +10,8 @@ import {
   type StandardErrorResponseBody,
   type StandardSchema,
   type StandardSchemaV1,
-} from "../contracts";
-import { isErrorResponseBody, SchemaValidationError } from "../errors";
+} from "../contracts/index.js";
+import { isErrorResponseBody, SchemaValidationError } from "../errors/index.js";
 import type {
   CallArgs,
   ClientConfig,
@@ -21,7 +21,7 @@ import type {
   InferEndpointErrorResponseByStatus,
   InferEndpointErrorStatus,
   InferSuccessResponse,
-} from "./types";
+} from "./types.js";
 
 /**
  * Source category for a `ContractError`.
@@ -583,11 +583,10 @@ export class Endpoint<
 
     try {
       if (args.body !== undefined && args.rawBody !== undefined) {
-        throw this.createError(
-          undefined,
-          "INVALID_REQUEST_BODY",
-          "Pass either body or rawBody, not both.",
-        );
+        throw this.createError({
+          code: "INVALID_REQUEST_BODY",
+          message: "Pass either body or rawBody, not both.",
+        });
       }
 
       const methodSupportsBody = methodSupportsRequestBody(
@@ -597,11 +596,10 @@ export class Endpoint<
         (args.body !== undefined || args.rawBody !== undefined) &&
         !methodSupportsBody
       ) {
-        throw this.createError(
-          undefined,
-          "INVALID_REQUEST_BODY",
-          `Request bodies are not supported for ${this.contract.method} contracts. Use POST, PUT, or PATCH for contract request bodies.`,
-        );
+        throw this.createError({
+          code: "INVALID_REQUEST_BODY",
+          message: `Request bodies are not supported for ${this.contract.method} contracts. Use POST, PUT, or PATCH for contract request bodies.`,
+        });
       }
 
       let requestBody: BodyInit | undefined;
@@ -613,7 +611,7 @@ export class Endpoint<
 
       if (args.body !== undefined && methodSupportsBody) {
         let bodyToSend = args.body;
-        if (this.config.validate && this.contract.body) {
+        if (this.config.validateInput && this.contract.body) {
           try {
             bodyToSend = (await validateSchema(
               this.contract.body,
@@ -621,12 +619,11 @@ export class Endpoint<
             )) as typeof bodyToSend;
           } catch (err) {
             if (err instanceof SchemaValidationError) {
-              throw this.createError(
-                422,
-                "VALIDATION_ERROR",
-                "Body validation failed",
-                err.issues,
-              );
+              throw this.createError({
+                code: "INPUT_VALIDATION_ERROR",
+                message: "Body validation failed",
+                details: err.issues,
+              });
             }
             throw err;
           }
@@ -643,19 +640,28 @@ export class Endpoint<
         args.headers as Record<string, string> | undefined,
         requestBodyType === "json",
       );
-      if (this.config.validate) {
+      const idempotencyMeta = this.contract.metadata?.idempotency;
+      if (idempotencyMeta) {
+        const idempotencyHeader = (
+          idempotencyMeta.header ?? "idempotency-key"
+        ).toLowerCase();
+        if (!headers[idempotencyHeader]) {
+          headers[idempotencyHeader] =
+            args.idempotencyKey ?? crypto.randomUUID();
+        }
+      }
+      if (this.config.validateInput) {
         const headerSchemas = getContractHeaderSchemas(this.contract.headers);
         if (headerSchemas.length > 0) {
           try {
             headers = await validateHeaderSchemas(headerSchemas, headers);
           } catch (err) {
             if (err instanceof SchemaValidationError) {
-              throw this.createError(
-                422,
-                "VALIDATION_ERROR",
-                "Headers validation failed",
-                err.issues,
-              );
+              throw this.createError({
+                code: "INPUT_VALIDATION_ERROR",
+                message: "Headers validation failed",
+                details: err.issues,
+              });
             }
             throw err;
           }
@@ -674,6 +680,7 @@ export class Endpoint<
       }
 
       const response = await fetchFn(url, options);
+      const shouldValidateResponses = this.config.validateResponses !== false;
 
       // Handle non-2xx responses
       if (!response.ok) {
@@ -682,35 +689,34 @@ export class Endpoint<
           errorBody = await parseResponseBody(response);
         } catch (parseErr) {
           // JSON parse failed — still report the HTTP error
-          throw this.createError(
-            response.status,
-            "INVALID_JSON",
-            createInvalidJsonMessage("error", response.status),
-            undefined,
-            parseErr,
-            undefined,
+          throw this.createError({
+            status: response.status,
+            code: "INVALID_JSON",
+            message: createInvalidJsonMessage("error", response.status),
+            cause: parseErr,
             response,
-            "contract",
-          );
+            source: "contract",
+          });
         }
 
-        const validatedError = await validateErrorBodyOrStandardEnvelope(
-          this.contract,
-          response,
-          errorBody,
-        );
+        const validatedError = shouldValidateResponses
+          ? await validateErrorBodyOrStandardEnvelope(
+              this.contract,
+              response,
+              errorBody,
+            )
+          : errorBody;
 
         const errorPayload = getErrorPayload(validatedError);
-        throw this.createError(
-          response.status,
-          errorPayload.code || "HTTP_ERROR",
-          errorPayload.message || response.statusText,
-          errorPayload.details,
-          undefined,
-          validatedError,
+        throw this.createError({
+          status: response.status,
+          code: errorPayload.code || "HTTP_ERROR",
+          message: errorPayload.message || response.statusText,
+          details: errorPayload.details,
+          body: validatedError,
           response,
-          "http",
-        );
+          source: "http",
+        });
       }
 
       // Parse response
@@ -718,71 +724,68 @@ export class Endpoint<
       try {
         data = await parseResponseBody(response);
       } catch (parseErr) {
-        throw this.createError(
-          response.status,
-          "INVALID_JSON",
-          createInvalidJsonMessage("success", response.status),
-          undefined,
-          parseErr,
-          undefined,
+        throw this.createError({
+          status: response.status,
+          code: "INVALID_JSON",
+          message: createInvalidJsonMessage("success", response.status),
+          cause: parseErr,
           response,
-          "contract",
-        );
+          source: "contract",
+        });
       }
 
       // Validate response if schema exists for this status
-      const statusKey = String(response.status);
-      const hasSchema = statusKey in this.contract.responses;
-      const hasDeclaredResponses =
-        Object.keys(this.contract.responses).length > 0;
-      const responseSchema = this.contract.responses[response.status];
-      if (hasSchema && responseSchema === null) {
-        if (data !== undefined && data !== null) {
-          throw this.createError(
-            response.status,
-            "RESPONSE_VALIDATION_ERROR",
-            `Response validation failed for ${this.contract.method} ${this.contract.path} (status ${response.status}, contract: ${this.contract.name})`,
-            [
-              {
-                message:
-                  "Response body must be empty for a null response schema.",
-              },
-            ],
-            undefined,
-            data,
-            response,
-            "contract",
-          );
-        }
-      } else if (hasSchema && responseSchema) {
-        try {
-          data = await validateSchema(responseSchema, data);
-        } catch (err) {
-          if (err instanceof SchemaValidationError) {
-            throw this.createError(
-              response.status,
-              "RESPONSE_VALIDATION_ERROR",
-              `Response validation failed for ${this.contract.method} ${this.contract.path} (status ${response.status}, contract: ${this.contract.name})`,
-              err.issues,
-              err,
-              data,
+      if (shouldValidateResponses) {
+        const statusKey = String(response.status);
+        const hasSchema = statusKey in this.contract.responses;
+        const hasDeclaredResponses =
+          Object.keys(this.contract.responses).length > 0;
+        const responseSchema = this.contract.responses[response.status];
+        if (hasSchema && responseSchema === null) {
+          if (data !== undefined && data !== null) {
+            throw this.createError({
+              status: response.status,
+              code: "RESPONSE_VALIDATION_ERROR",
+              message: `Response validation failed for ${this.contract.method} ${this.contract.path} (status ${response.status}, contract: ${this.contract.name})`,
+              details: [
+                {
+                  message:
+                    "Response body must be empty for a null response schema.",
+                },
+              ],
+              body: data,
               response,
-              "contract",
-            );
+              source: "contract",
+            });
           }
-          throw err;
+        } else if (hasSchema && responseSchema) {
+          try {
+            data = await validateSchema(responseSchema, data);
+          } catch (err) {
+            if (err instanceof SchemaValidationError) {
+              throw this.createError({
+                status: response.status,
+                code: "RESPONSE_VALIDATION_ERROR",
+                message: `Response validation failed for ${this.contract.method} ${this.contract.path} (status ${response.status}, contract: ${this.contract.name})`,
+                details: err.issues,
+                cause: err,
+                body: data,
+                response,
+                source: "contract",
+              });
+            }
+            throw err;
+          }
+        } else if (!hasSchema && hasDeclaredResponses) {
+          throw this.createError({
+            status: response.status,
+            code: "UNDECLARED_RESPONSE_STATUS",
+            message: `Server returned undeclared status ${response.status} for ${this.contract.method} ${this.contract.path} (contract: ${this.contract.name})`,
+            body: data,
+            response,
+            source: "contract",
+          });
         }
-      } else if (!hasSchema && hasDeclaredResponses) {
-        throw this.createError(
-          response.status,
-          "UNDECLARED_RESPONSE_STATUS",
-          `Server returned undeclared status ${response.status} for ${this.contract.method} ${this.contract.path} (contract: ${this.contract.name})`,
-          undefined,
-          undefined,
-          data,
-          response,
-          "contract",
-        );
       }
 
       return {
@@ -801,16 +804,12 @@ export class Endpoint<
           response: error.response,
         };
       }
-      const error = this.createError(
-        undefined,
-        "NETWORK_ERROR",
-        err instanceof Error ? err.message : "Network request failed",
-        undefined,
-        err,
-        undefined,
-        undefined,
-        "network",
-      ) as InferEndpointContractError<TContract>;
+      const error = this.createError({
+        code: "NETWORK_ERROR",
+        message: err instanceof Error ? err.message : "Network request failed",
+        cause: err,
+        source: "network",
+      }) as InferEndpointContractError<TContract>;
       return {
         ok: false,
         status: error.status,
@@ -843,7 +842,7 @@ export class Endpoint<
     // Replace path parameters
     if (path && parsedPath.keys.length > 0) {
       // Validate path params if schema exists and validation is enabled
-      if (this.config.validate && this.contract.pathParams) {
+      if (this.config.validateInput && this.contract.pathParams) {
         try {
           pathToSerialize = (await validateSchema(
             this.contract.pathParams,
@@ -851,12 +850,11 @@ export class Endpoint<
           )) as PathParams;
         } catch (err) {
           if (err instanceof SchemaValidationError) {
-            throw this.createError(
-              422,
-              "VALIDATION_ERROR",
-              "Path params validation failed",
-              err.issues,
-            );
+            throw this.createError({
+              code: "INPUT_VALIDATION_ERROR",
+              message: "Path params validation failed",
+              details: err.issues,
+            });
           }
           throw err;
         }
@@ -894,7 +892,7 @@ export class Endpoint<
     let queryToSerialize = query;
     if (query) {
       // Validate query params if schema exists and validation is enabled
-      if (this.config.validate && this.contract.query) {
+      if (this.config.validateInput && this.contract.query) {
         try {
           queryToSerialize = (await validateSchema(
             this.contract.query,
@@ -902,12 +900,11 @@ export class Endpoint<
           )) as QueryParams;
         } catch (err) {
           if (err instanceof SchemaValidationError) {
-            throw this.createError(
-              422,
-              "VALIDATION_ERROR",
-              "Query params validation failed",
-              err.issues,
-            );
+            throw this.createError({
+              code: "INPUT_VALIDATION_ERROR",
+              message: "Query params validation failed",
+              details: err.issues,
+            });
           }
           throw err;
         }
@@ -987,26 +984,27 @@ export class Endpoint<
   /**
    * Create a contract error
    */
-  private createError(
-    status: number | undefined,
-    code: string,
-    message: string,
-    details?: unknown,
-    cause?: unknown,
-    body?: unknown,
-    response?: Response,
-    source: ContractErrorSource = "client",
-  ): AnyContractError {
+  private createError(options: {
+    code: string;
+    message: string;
+    status?: number;
+    details?: unknown;
+    cause?: unknown;
+    body?: unknown;
+    response?: Response;
+    source?: ContractErrorSource;
+  }): AnyContractError {
+    const source = options.source ?? "client";
+    const isLocalError = source === "client" || source === "network";
     return new ContractError({
       source,
-      status: source === "client" || source === "network" ? undefined : status,
-      code,
-      message,
-      body: source === "client" || source === "network" ? undefined : body,
-      details,
-      response:
-        source === "client" || source === "network" ? undefined : response,
-      cause,
+      status: isLocalError ? undefined : options.status,
+      code: options.code,
+      message: options.message,
+      body: isLocalError ? undefined : options.body,
+      details: options.details,
+      response: isLocalError ? undefined : options.response,
+      cause: options.cause,
     }) as AnyContractError;
   }
 }

package/src/client/error-messages.ts

@@ -0,0 +1,35 @@
+import { isContractError } from "./client.js";
+
+/**
+ * User-facing copy overrides keyed by error code.
+ */
+export type ErrorMessageOverrides = Partial<Record<string, string>>;
+
+/**
+ * Map an unknown error to user-facing copy.
+ *
+ * Non-`ContractError` values return the fallback. Override copy per catalog
+ * code with `overrides`. Client-side input validation failures return a
+ * generic "check the highlighted fields" message; other contract errors
+ * return the error message.
+ */
+export function contractErrorMessage(
+  error: unknown,
+  fallback: string,
+  overrides: ErrorMessageOverrides = {},
+): string {
+  if (!isContractError(error)) {
+    return fallback;
+  }
+
+  const override = error.code ? overrides[error.code] : undefined;
+  if (override) {
+    return override;
+  }
+
+  if (error.hasSource("client") && error.hasCode("INPUT_VALIDATION_ERROR")) {
+    return "Check the highlighted fields and try again.";
+  }
+
+  return error.message;
+}

package/src/client/index.ts

@@ -7,7 +7,7 @@
 /**
  * Schema validation error re-exported for client users.
  */
-export { SchemaValidationError } from "../errors";
+export { SchemaValidationError } from "../errors/index.js";
 /**
  * Contract client error types.
  */
@@ -23,7 +23,7 @@ export type {
   InferEndpointErrorCode,
   NetworkContractError,
   ResponseContractError,
-} from "./client";
+} from "./client.js";
 /**
  * Contract client runtime helpers.
  */
@@ -33,11 +33,19 @@ export {
   createClient,
   Endpoint,
   isContractError,
-} from "./client";
+} from "./client.js";
+/**
+ * Client error message helpers.
+ */
+export {
+  contractErrorMessage,
+  type ErrorMessageOverrides,
+} from "./error-messages.js";
 /**
  * Contract client inference and call types.
  */
 export type {
+  AutoProvidedHeaders,
   CallArgs,
   ClientConfig,
   EndpointCallArgs,
@@ -54,4 +62,4 @@ export type {
   InferPathParams,
   InferQuery,
   InferSuccessResponse,
-} from "./types";
+} from "./types.js";

package/src/client/types.ts

@@ -6,8 +6,8 @@ import type {
   InferOutput,
   StandardSchema,
   StandardSchemaV1,
-} from "../contracts";
-import type { ErrorResponseBody } from "../errors";
+} from "../contracts/index.js";
+import type { ErrorResponseBody } from "../errors/index.js";
 
 /**
  * Configuration for a Beignet contract client.
@@ -29,8 +29,20 @@ export type ClientConfig<TProvidedHeaders extends string = never> = {
    * Fetch implementation. Defaults to global `fetch`.
    */
   fetch?: typeof fetch;
-  /** Enable client-side input validation for path, query, and body. Default: false. */
-  validate?: boolean;
+  /**
+   * Validate path params, query params, request bodies, and declared request
+   * headers against contract schemas before sending. Failures throw a
+   * client-source `ContractError` with code `INPUT_VALIDATION_ERROR`.
+   * Default: false.
+   */
+  validateInput?: boolean;
+  /**
+   * Validate response bodies (success and declared error responses) against
+   * contract schemas. Disabling this returns success bodies as-is and skips
+   * contract-drift checks such as undeclared response statuses.
+   * Default: true.
+   */
+  validateResponses?: boolean;
 };
 
 type PathParamPrimitive = string | number | boolean;
@@ -300,6 +312,25 @@ type ProvidedHeaderKeys<THeaders, TProvidedHeaders extends string> = Extract<
   TProvidedHeaders
 >;
 
+/**
+ * Header names the client fills in automatically from contract metadata.
+ *
+ * Contracts with idempotency metadata get their idempotency key header
+ * generated per call, so typed calls may omit it. When the metadata header
+ * name is widened to `string`, only the default `idempotency-key` header is
+ * treated as auto-provided so other required headers stay required.
+ */
+export type AutoProvidedHeaders<TContract extends HttpContractConfig> =
+  TContract["metadata"] extends { idempotency: infer M }
+    ? M extends { header: infer H extends string }
+      ? string extends H
+        ? "idempotency-key"
+        : Lowercase<H>
+      : M extends object
+        ? "idempotency-key"
+        : never
+    : never;
+
 type ApplyProvidedHeaders<THeaders, TProvidedHeaders extends string> = Omit<
   THeaders,
   ProvidedHeaderKeys<THeaders, TProvidedHeaders>
@@ -312,7 +343,10 @@ type HeaderInput<
 > =
   InferHeaders<TContract> extends undefined
     ? Record<string, string>
-    : ApplyProvidedHeaders<InferHeaders<TContract>, TProvidedHeaders>;
+    : ApplyProvidedHeaders<
+        InferHeaders<TContract>,
+        TProvidedHeaders | AutoProvidedHeaders<TContract>
+      >;
 
 type HeadersArgs<
   TContract extends HttpContractConfig,
@@ -341,6 +375,11 @@ export type EndpointCallArgs<
      * and is not validated or JSON-serialized.
      */
     rawBody?: TContract["method"] extends BodyHttpMethod ? BodyInit : never;
+    /**
+     * Idempotency key to send instead of an auto-generated one. Use for
+     * retry-with-same-key flows on contracts with idempotency metadata.
+     */
+    idempotencyKey?: string;
     /**
      * Abort signal passed to fetch.
      */

package/src/client-only.ts

@@ -0,0 +1,7 @@
+/**
+ * Static Beignet lint marker for modules intended for client-side imports.
+ *
+ * Host frameworks may provide their own runtime-only enforcement. This marker
+ * is intentionally a no-op so Beignet can enforce intent through `beignet lint`.
+ */
+export const beignetClientOnly = true;

package/src/config/index.ts

@@ -96,9 +96,9 @@ export interface ReadEnvOptions {
 }
 
 /**
- * Options for defining a single validated env loader.
+ * Options for creating a single validated env loader.
  */
-export interface DefineEnvOptions<Schema extends StandardSchemaV1> {
+export interface CreateEnvLoaderOptions<Schema extends StandardSchemaV1> {
   /**
    * Standard Schema for validating the full environment object.
    */
@@ -133,7 +133,7 @@ export interface DefineEnvOptions<Schema extends StandardSchemaV1> {
 }
 
 /**
- * Validated env loader returned by `defineEnv(...)`.
+ * Validated env loader returned by `createEnvLoader(...)`.
  */
 export interface EnvInstance<Out> {
   /**
@@ -396,13 +396,13 @@ function wrapEnvError(err: unknown, prefix?: string): Error {
 }
 
 /**
- * Define a reusable validated env loader.
+ * Create a reusable validated env loader.
  *
  * This is useful for provider config and app-level config objects that are
  * loaded from a prefixed subset of the environment.
  */
-export function defineEnv<Schema extends StandardSchemaV1>(
-  options: DefineEnvOptions<Schema>,
+export function createEnvLoader<Schema extends StandardSchemaV1>(
+  options: CreateEnvLoaderOptions<Schema>,
 ): EnvInstance<InferOutput<Schema>> {
   const {
     schema,