@beignet/core 0.0.3 → 0.0.4

package/src/contracts/schema-shape.ts

@@ -0,0 +1,75 @@
+/**
+ * Internal schema shape helpers shared by server route registration and
+ * OpenAPI generation.
+ *
+ * These helpers are intentionally zod-free: zod is an optional peer
+ * dependency, so shape extraction duck-types Zod's `_def.shape` internals and
+ * returns undefined for schemas it cannot introspect. This module is not
+ * exported from the package index.
+ */
+
+/**
+ * Extract the field shape (field name → field schema) from an object schema.
+ *
+ * Returns undefined when the schema is not an introspectable object schema,
+ * for example a non-Zod Standard Schema.
+ */
+export function getObjectSchemaShape(
+  schema: unknown,
+): Record<string, unknown> | undefined {
+  if (!schema || typeof schema !== "object") return undefined;
+
+  const schemaDef = (schema as Record<string, unknown>)?._def;
+  if (!schemaDef || typeof schemaDef !== "object") return undefined;
+
+  if (!("shape" in schemaDef)) return undefined;
+
+  let shape: unknown;
+  if (typeof schemaDef.shape === "function") {
+    shape = schemaDef.shape();
+  } else if (typeof schemaDef.shape === "object") {
+    shape = schemaDef.shape;
+  }
+
+  if (!shape || typeof shape !== "object") return undefined;
+
+  return shape as Record<string, unknown>;
+}
+
+/**
+ * Compare a path template's dynamic keys against a pathParams schema shape.
+ */
+export function comparePathParamsToTemplate(args: {
+  pathKeys: readonly string[];
+  shapeKeys: readonly string[];
+}): { missingKeys: string[]; extraKeys: string[] } {
+  const missingKeys = args.pathKeys.filter(
+    (key) => !args.shapeKeys.includes(key),
+  );
+  const extraKeys = args.shapeKeys.filter(
+    (key) => !args.pathKeys.includes(key),
+  );
+  return { missingKeys, extraKeys };
+}
+
+/**
+ * Format a pathParams/template mismatch for error messages.
+ *
+ * Shared so server registration and OpenAPI generation report the same
+ * diagnostic details.
+ */
+export function formatPathParamsMismatch(args: {
+  missingKeys: readonly string[];
+  extraKeys: readonly string[];
+}): string {
+  return [
+    args.missingKeys.length > 0
+      ? `missing pathParams keys: ${args.missingKeys.join(", ")}`
+      : undefined,
+    args.extraKeys.length > 0
+      ? `extra pathParams keys: ${args.extraKeys.join(", ")}`
+      : undefined,
+  ]
+    .filter(Boolean)
+    .join("; ");
+}

package/src/contracts/success-status.ts

@@ -0,0 +1,68 @@
+import type { HttpContractConfig } from "./types.js";
+
+type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+type ToNumber<S extends string> = S extends `${infer N extends number}`
+  ? N
+  : never;
+type Any2xxCode = ToNumber<`2${Digit}${Digit}`>;
+type NumericKey<K> = K extends number
+  ? K
+  : K extends `${infer N extends number}`
+    ? N
+    : never;
+
+type UnionToIntersection<T> = (
+  T extends unknown
+    ? (value: T) => void
+    : never
+) extends (value: infer I) => void
+  ? I
+  : never;
+
+/**
+ * All declared 2xx status codes from a contract `responses` record, as
+ * numeric literal keys.
+ */
+export type Success2xxKeys<TResponses extends object> = {
+  [K in keyof TResponses]: NumericKey<K> extends Any2xxCode
+    ? NumericKey<K>
+    : never;
+}[keyof TResponses];
+
+/**
+ * Whether a contract `responses` record declares exactly one 2xx status.
+ */
+export type IsSingle2xx<TResponses extends object> = [
+  Success2xxKeys<TResponses>,
+] extends [never]
+  ? false
+  : [Success2xxKeys<TResponses>] extends [
+        UnionToIntersection<Success2xxKeys<TResponses>>,
+      ]
+    ? true
+    : false;
+
+/**
+ * List the declared 2xx statuses of a contract at runtime.
+ */
+export function getSuccess2xxStatuses(
+  contract: Pick<HttpContractConfig, "responses">,
+): number[] {
+  return Object.keys(contract.responses)
+    .map((status) => Number(status))
+    .filter(
+      (status) => Number.isInteger(status) && status >= 200 && status < 300,
+    )
+    .sort((a, b) => a - b);
+}
+
+/**
+ * Resolve the sole declared 2xx status of a contract, or `undefined` when the
+ * contract declares zero or multiple 2xx statuses.
+ */
+export function inferSoleSuccessStatus(
+  contract: Pick<HttpContractConfig, "responses">,
+): number | undefined {
+  const statuses = getSuccess2xxStatuses(contract);
+  return statuses.length === 1 ? statuses[0] : undefined;
+}

package/src/contracts/types.ts

@@ -1,7 +1,7 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { IdempotencyMeta } from "../idempotency";
-import type { OpenAPIOperationMeta } from "./openapi-meta";
-import type { RateLimitMeta } from "./rate-limit";
+import type { IdempotencyMeta } from "../idempotency/index.js";
+import type { OpenAPIOperationMeta } from "./openapi-meta.js";
+import type { RateLimitMeta } from "./rate-limit.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -72,6 +72,21 @@ export type ResponsesFromErrorDefinitions<T extends ContractErrorResponses> = {
   [K in keyof T as T[K]["status"]]: StandardErrorResponseSchema;
 };
 
+/**
+ * Merge catalog errors already declared in contract metadata with newly
+ * declared error definitions.
+ *
+ * `.errors()` declarations compose: contracts keep the union of group-declared
+ * and route-declared catalog errors. Later declarations win when the same
+ * catalog key is declared twice.
+ */
+export type MergedContractErrorResponses<
+  TMeta extends ContractMeta,
+  TErrorDefs extends ContractErrorResponses,
+> = TMeta["errors"] extends ContractErrorResponses
+  ? Omit<TMeta["errors"], keyof TErrorDefs> & TErrorDefs
+  : TErrorDefs;
+
 /**
  * Header schema declaration for a contract.
  */
@@ -222,13 +237,25 @@ export type ContractMeta = {
   /**
    * Optional idempotency configuration for this contract.
    *
-   * This metadata is intended for hooks, docs, and OpenAPI. Use cases should
-   * still call `runIdempotently(...)` for workflows that must be retry-safe.
+   * Enforced at the HTTP boundary by `createIdempotencyHooks(...)`.
+   * `runIdempotently(...)` remains the primitive for non-HTTP workflows.
    */
   idempotency?: IdempotencyMeta;
   [namespace: string]: unknown;
 };
 
+/**
+ * Omit metadata keys while preserving literal property types.
+ *
+ * `ContractMeta` carries an index signature, so the built-in `Omit` collapses
+ * `keyof` to `string` and erases literal metadata such as
+ * `idempotency: { header: "idempotency-key" }` that typed clients rely on.
+ * Key remapping keeps known properties and the index signature intact.
+ */
+export type OmitMetaKeys<TMeta, K extends PropertyKey> = {
+  [P in keyof TMeta as P extends K ? never : P]: TMeta[P];
+};
+
 /**
  * Plain HTTP contract configuration consumed by server, client, and tooling.
  */

package/src/contracts/utils.ts

@@ -1,5 +1,8 @@
-import { type PathTemplateSegment, parsePathTemplate } from "./path-template";
-import type { HttpMethod } from "./types";
+import {
+  type PathTemplateSegment,
+  parsePathTemplate,
+} from "./path-template.js";
+import type { HttpMethod } from "./types.js";
 
 const methodNameMap: Record<HttpMethod, string> = {
   GET: "get",

package/src/domain/events.ts

@@ -1,5 +1,9 @@
-import type { EventDef, InferEventPayload, StandardSchema } from "../events";
-import { defineEvent } from "../events";
+import type {
+  EventDef,
+  InferEventPayload,
+  StandardSchema,
+} from "../events/index.js";
+import { defineEvent } from "../events/index.js";
 
 /**
  * Domain event definition with a stable name and payload schema.

package/src/domain/index.ts

@@ -9,10 +9,10 @@
  * - A Domain Event helper (defineDomainEvent)
  */
 
-export { defineEntity, type EntityDef, type EntityInstance } from "./entity";
+export { defineEntity, type EntityDef, type EntityInstance } from "./entity.js";
 export {
   type DomainEventDef,
   defineDomainEvent,
   type InferEventPayload,
-} from "./events";
-export { defineValueObject, type ValueObjectDef } from "./value-object";
+} from "./events.js";
+export { defineValueObject, type ValueObjectDef } from "./value-object.js";

package/src/errors/catalog.ts

@@ -26,6 +26,8 @@ export interface ErrorDef<
    *
    * Beignet uses this for TypeScript inference. Details are not runtime
    * validated by `AppError`; validate before constructing errors when needed.
+   * Details become public response data when the error crosses the HTTP
+   * boundary, so use app-owned safe fields instead of raw diagnostics.
    */
   details?: TDetails;
 }
@@ -64,7 +66,13 @@ export class AppError<TDef extends ErrorDef = ErrorDef> extends Error {
   readonly [APP_ERROR_BRAND] = true;
   /** Error definition from the catalog. */
   readonly def: TDef;
-  /** Optional structured details for clients, logs, or UI. */
+  /**
+   * Optional structured details for clients or UI.
+   *
+   * Beignet does not automatically redact route-owned error details. Keep
+   * provider errors, stack traces, secrets, and private content in `cause`,
+   * logs, or error reporting instead.
+   */
   readonly details?: InferErrorDetails<TDef>;
 
   constructor(

package/src/errors/http.ts

@@ -4,7 +4,7 @@
  * A base catalog of common HTTP-related errors that apps can reuse and extend.
  */
 
-import { defineErrors } from "./catalog";
+import { defineErrors } from "./catalog.js";
 
 /**
  * A base catalog of common HTTP-related errors.
@@ -52,6 +52,16 @@ export const httpErrors = defineErrors({
     status: 409,
     message: "Conflict",
   },
+  IdempotencyConflict: {
+    code: "IDEMPOTENCY_CONFLICT",
+    status: 409,
+    message: "Idempotency key was already used with a different request",
+  },
+  IdempotencyInProgress: {
+    code: "IDEMPOTENCY_IN_PROGRESS",
+    status: 409,
+    message: "Idempotency key is already being processed",
+  },
   TooManyRequests: {
     code: "TOO_MANY_REQUESTS",
     status: 429,

package/src/errors/index.ts

@@ -14,15 +14,15 @@ export {
   type ErrorDef,
   type InferErrorDetails,
   isAppError,
-} from "./catalog";
+} from "./catalog.js";
 // HTTP error helpers
-export { type HttpErrorCatalog, httpErrors } from "./http";
+export { type HttpErrorCatalog, httpErrors } from "./http.js";
 // Error response utilities
 export {
   createErrorResponseBody,
   type ErrorResponseBody,
   isErrorResponseBody,
   toErrorResponseBody,
-} from "./response";
+} from "./response.js";
 // Schema validation error (shared across client/core/server)
-export { SchemaValidationError, type ValidationIssue } from "./validation";
+export { SchemaValidationError, type ValidationIssue } from "./validation.js";

package/src/errors/response.ts

@@ -2,7 +2,7 @@
  * Standard error response schema and utilities for Beignet
  */
 
-import type { AppError, ErrorDef } from "./catalog";
+import type { AppError, ErrorDef } from "./catalog.js";
 
 /**
  * Standard Beignet error response body.
@@ -18,6 +18,9 @@ export interface ErrorResponseBody {
   message: string;
   /**
    * Optional structured details.
+   *
+   * These details are sent to clients. Beignet does not automatically redact
+   * app-owned response details, so only include values that are safe to expose.
    */
   details?: unknown;
   /**

package/src/events/index.ts

@@ -168,9 +168,9 @@ export interface RegisterListenersOptions<Ctx> {
 }
 
 /**
- * Context-bound event helper factory.
+ * Context-bound listener helper factory.
  */
-export interface EventHandlers<Ctx> {
+export interface Listeners<Ctx> {
   /**
    * Define a listener with the bound context type.
    */
@@ -178,15 +178,6 @@ export interface EventHandlers<Ctx> {
     event: E,
     options: DefineListenerOptions<E, Ctx, Name>,
   ): ListenerDef<E, Ctx, Name>;
-
-  /**
-   * Register listeners with an event bus.
-   */
-  registerListeners(
-    eventBus: EventBusLike,
-    listeners: readonly ListenerDef<EventDef, Ctx>[],
-    options?: RegisterListenersOptions<Ctx>,
-  ): () => void;
 }
 
 /**
@@ -280,10 +271,7 @@ export function defineEvent<
   };
 }
 
-/**
- * Define a listener for one event.
- */
-export function defineListener<
+function defineListenerImpl<
   E extends EventDef,
   Ctx = unknown,
   Name extends string = string,
@@ -358,23 +346,21 @@ export function registerListeners<Ctx>(
 }
 
 /**
- * Create event helper methods bound to an application context type.
+ * Create listener helper methods bound to an application context type.
+ *
+ * Call it once in `lib/listeners.ts`:
+ *
+ * ```ts
+ * export const { defineListener } = createListeners<AppContext>();
+ * ```
  */
-export function createEventHandlers<Ctx>(): EventHandlers<Ctx> {
+export function createListeners<Ctx>(): Listeners<Ctx> {
   return {
     defineListener<E extends EventDef, Name extends string = string>(
       event: E,
       options: DefineListenerOptions<E, Ctx, Name>,
     ): ListenerDef<E, Ctx, Name> {
-      return defineListener(event, options);
-    },
-
-    registerListeners(
-      eventBus: EventBusLike,
-      listeners: readonly ListenerDef<EventDef, Ctx>[],
-      options: RegisterListenersOptions<Ctx> = {},
-    ): () => void {
-      return registerListeners(eventBus, listeners, options);
+      return defineListenerImpl(event, options);
     },
   };
 }

package/src/idempotency/index.ts

@@ -38,13 +38,15 @@ export type IdempotencyScopeMode =
 
 /**
  * Contract metadata for idempotency-aware routes.
+ *
+ * This metadata is enforced at the HTTP boundary by
+ * `createIdempotencyHooks(...)` from `@beignet/core/server`.
+ * `runIdempotently(...)` remains the primitive for non-HTTP workflows such as
+ * jobs, listeners, webhooks, and schedules.
  */
 export interface IdempotencyMeta {
   /**
    * Whether this operation requires an idempotency key at the HTTP boundary.
-   *
-   * This is metadata for hooks, docs, and generated OpenAPI. Use cases should
-   * still call `runIdempotently(...)` for workflows that must be retry-safe.
    */
   required?: boolean;
 

package/src/jobs/index.ts

@@ -306,7 +306,7 @@ export interface InlineJobDispatcher<Ctx = unknown> {
 /**
  * Context-bound job helper factory.
  */
-export interface JobHandlers<Ctx> {
+export interface Jobs<Ctx> {
   /**
    * Define a job with the bound context type.
    */
@@ -314,13 +314,6 @@ export interface JobHandlers<Ctx> {
     name: Name,
     options: DefineJobOptions<Name, Payload, Ctx>,
   ): JobDef<Name, Payload, Ctx>;
-
-  /**
-   * Create an inline dispatcher with the bound context type.
-   */
-  createInlineJobDispatcher(
-    options?: InlineJobDispatcherOptions<Ctx>,
-  ): InlineJobDispatcher<Ctx>;
 }
 
 /**
@@ -555,14 +548,7 @@ async function resolveCtx<Ctx>(
   return ctx as Ctx;
 }
 
-/**
- * Define a typed job.
- *
- * Retry options are provider hints. Inline dispatchers validate payloads and
- * call `handle(...)` immediately; durable providers may enqueue or schedule the
- * job according to their own runtime.
- */
-export function defineJob<
+function defineJobImpl<
   Name extends string,
   Payload extends StandardSchema,
   Ctx = unknown,
@@ -624,20 +610,24 @@ export function createInlineJobDispatcher<Ctx>(
 
 /**
  * Create job helper methods bound to an application context type.
+ *
+ * Call it once in `lib/jobs.ts`:
+ *
+ * ```ts
+ * export const { defineJob } = createJobs<AppContext>();
+ * ```
+ *
+ * Retry options are provider hints. Inline dispatchers validate payloads and
+ * call `handle(...)` immediately; durable providers may enqueue or schedule the
+ * job according to their own runtime.
  */
-export function createJobHandlers<Ctx>(): JobHandlers<Ctx> {
+export function createJobs<Ctx>(): Jobs<Ctx> {
   return {
     defineJob<Name extends string, Payload extends StandardSchema>(
       name: Name,
       options: DefineJobOptions<Name, Payload, Ctx>,
     ): JobDef<Name, Payload, Ctx> {
-      return defineJob(name, options);
-    },
-
-    createInlineJobDispatcher(
-      options: InlineJobDispatcherOptions<Ctx> = {},
-    ): InlineJobDispatcher<Ctx> {
-      return createInlineJobDispatcher(options);
+      return defineJobImpl(name, options);
     },
   };
 }

package/src/notifications/index.ts

@@ -1,7 +1,7 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { SendMailOptions } from "../mail";
-import type { ProviderInstrumentationTarget } from "../providers";
-import { createProviderInstrumentation } from "../providers";
+import type { SendMailOptions } from "../mail/index.js";
+import type { ProviderInstrumentationTarget } from "../providers/index.js";
+import { createProviderInstrumentation } from "../providers/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -336,7 +336,7 @@ export type MailNotificationRenderer<
 /**
  * Context-bound notification helper factory.
  */
-export interface NotificationHandlers<Ctx> {
+export interface Notifications<Ctx> {
   /**
    * Define a notification with the bound context type.
    */
@@ -344,13 +344,6 @@ export interface NotificationHandlers<Ctx> {
     name: Name,
     options: DefineNotificationOptions<Payload, Ctx>,
   ): NotificationDef<Name, Payload, Ctx>;
-
-  /**
-   * Create an inline dispatcher with the bound context type.
-   */
-  createInlineNotificationDispatcher(
-    options?: InlineNotificationDispatcherOptions<Ctx>,
-  ): NotificationPort;
 }
 
 /**
@@ -495,14 +488,7 @@ function summarizeResults(results: readonly NotificationChannelResult[]) {
   return { sent, skipped, failed };
 }
 
-/**
- * Define a typed notification.
- *
- * Notifications represent user-facing communication intent. Channel handlers
- * decide how that intent becomes mail, SMS, push, in-app delivery, or another
- * app-owned channel.
- */
-export function defineNotification<
+function defineNotificationImpl<
   Name extends string,
   Payload extends StandardSchema,
   Ctx = unknown,
@@ -752,20 +738,24 @@ export function createMemoryNotificationPort(
 
 /**
  * Create notification helper methods bound to an application context type.
+ *
+ * Call it once in `lib/notifications.ts`:
+ *
+ * ```ts
+ * export const { defineNotification } = createNotifications<AppContext>();
+ * ```
+ *
+ * Notifications represent user-facing communication intent. Channel handlers
+ * decide how that intent becomes mail, SMS, push, in-app delivery, or another
+ * app-owned channel.
  */
-export function createNotificationHandlers<Ctx>(): NotificationHandlers<Ctx> {
+export function createNotifications<Ctx>(): Notifications<Ctx> {
   return {
     defineNotification<Name extends string, Payload extends StandardSchema>(
       name: Name,
       options: DefineNotificationOptions<Payload, Ctx>,
     ): NotificationDef<Name, Payload, Ctx> {
-      return defineNotification(name, options);
-    },
-
-    createInlineNotificationDispatcher(
-      options: InlineNotificationDispatcherOptions<Ctx> = {},
-    ): NotificationPort {
-      return createInlineNotificationDispatcher(options);
+      return defineNotificationImpl(name, options);
     },
   };
 }