@beignet/core 0.0.34 → 0.0.36

package/src/client/client.ts

@@ -485,9 +485,11 @@ async function validateHeaderSchemas(
 type PrimitiveParam = string | number | boolean;
 type QueryParamValue =
   | PrimitiveParam
+  | Date
+  | Record<string, unknown>
   | null
   | undefined
-  | Array<PrimitiveParam>;
+  | Array<PrimitiveParam | Date | Record<string, unknown>>;
 
 type PathParams = Record<string, PrimitiveParam>;
 type QueryParams = Record<string, QueryParamValue>;
@@ -946,26 +948,12 @@ export class Endpoint<
       const normalizedQuery = queryToSerialize ?? query;
       for (const [key, value] of Object.entries(normalizedQuery)) {
         if (value !== undefined && value !== null) {
-          if (typeof value === "object" && !Array.isArray(value)) {
-            throw new ContractError({
-              source: "client",
-              code: "INVALID_QUERY_PARAM",
-              message: `Query parameter "${key}" contains a non-serializable object. Use primitive values or arrays of primitives.`,
-            });
-          }
           if (Array.isArray(value)) {
             for (const v of value) {
-              if (typeof v === "object" && v !== null) {
-                throw new ContractError({
-                  source: "client",
-                  code: "INVALID_QUERY_PARAM",
-                  message: `Query parameter "${key}" contains a non-serializable array element. Use primitive values only.`,
-                });
-              }
-              params.append(key, String(v));
+              params.append(key, this.serializeQueryParam(key, v));
             }
           } else {
-            params.append(key, String(value));
+            params.append(key, this.serializeQueryParam(key, value));
           }
         }
       }
@@ -983,6 +971,42 @@ export class Endpoint<
     return baseUrl + url;
   }
 
+  private serializeQueryParam(key: string, value: unknown): string {
+    if (
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      return String(value);
+    }
+
+    if (value instanceof Date) {
+      if (!Number.isFinite(value.getTime())) {
+        throw this.invalidQueryParam(key, "contains an invalid Date");
+      }
+      return value.toISOString();
+    }
+
+    if (typeof value === "object" && value !== null) {
+      try {
+        const serialized = JSON.stringify(value);
+        if (serialized !== undefined) return serialized;
+      } catch {
+        // Report the contract/query key below instead of leaking JSON internals.
+      }
+    }
+
+    throw this.invalidQueryParam(key, "contains a non-serializable value");
+  }
+
+  private invalidQueryParam(key: string, reason: string): ContractError {
+    return new ContractError({
+      source: "client",
+      code: "INVALID_QUERY_PARAM",
+      message: `Query parameter "${key}" ${reason}. Use primitive values, Dates, JSON-serializable objects, or arrays of those values.`,
+    });
+  }
+
   /**
    * Build request headers
    */

package/src/contracts/contract-builder.ts

@@ -5,6 +5,7 @@ import {
   mergeCatalogErrors,
   responsesFromErrors,
 } from "./catalog-errors.js";
+import { mergeContractMeta } from "./metadata.js";
 import type { OpenAPIOperationMeta } from "./openapi-meta.js";
 import { parsePathTemplate } from "./path-template.js";
 import type {
@@ -15,6 +16,7 @@ import type {
   ContractResponses,
   HttpContractConfig,
   HttpMethod,
+  MergeContractMeta,
   MergedContractErrorResponses,
   OmitMetaKeys,
   ResponsesFromErrorDefinitions,
@@ -436,7 +438,7 @@ export class ContractBuilder<
     TBody,
     THeaders,
     TResponses,
-    OmitMetaKeys<TMeta, keyof TNewMeta> & TNewMeta,
+    MergeContractMeta<TMeta, TNewMeta>,
     TPath
   > {
     return new ContractBuilder({
@@ -451,18 +453,15 @@ export class ContractBuilder<
       headers: this._headers,
       body: this._body,
       responses: this._responses,
-      metadata: {
-        ...this._meta,
-        ...newMeta,
-      } as unknown as OmitMetaKeys<TMeta, keyof TNewMeta> & TNewMeta,
+      metadata: mergeContractMeta(this._meta, newMeta),
     });
   }
 
   /**
    * Merge OpenAPI operation metadata into this contract.
    */
-  openapi(
-    patch: Partial<OpenAPIOperationMeta>,
+  openapi<TPatch extends Partial<OpenAPIOperationMeta>>(
+    patch: TPatch,
   ): ContractBuilder<
     TMethod,
     TPathParams,
@@ -470,10 +469,9 @@ export class ContractBuilder<
     TBody,
     THeaders,
     TResponses,
-    TMeta,
+    MergeContractMeta<TMeta, { openapi: TPatch }>,
     TPath
   > {
-    const existingOpenApi = this._meta.openapi ?? {};
     return new ContractBuilder({
       kind: this.kind,
       name: this.name,
@@ -486,13 +484,7 @@ export class ContractBuilder<
       headers: this._headers,
       body: this._body,
       responses: this._responses,
-      metadata: {
-        ...this._meta,
-        openapi: {
-          ...existingOpenApi,
-          ...patch,
-        },
-      } as TMeta,
+      metadata: mergeContractMeta(this._meta, { openapi: patch }),
     });
   }
 }

package/src/contracts/contract-group.ts

@@ -5,6 +5,7 @@ import {
   responsesFromErrors,
 } from "./catalog-errors.js";
 import { ContractBuilder } from "./contract-builder.js";
+import { mergeContractMeta } from "./metadata.js";
 import { parsePathTemplate } from "./path-template.js";
 import type {
   ContractErrorResponses,
@@ -12,6 +13,7 @@ import type {
   ContractMeta,
   ContractResponses,
   HttpMethod,
+  MergeContractMeta,
   MergedContractErrorResponses,
   OmitMetaKeys,
   ResponsesFromErrorDefinitions,
@@ -149,17 +151,13 @@ export class ContractGroup<
     meta: TNewMeta,
   ): ContractGroup<
     TSharedResponses,
-    OmitMetaKeys<TSharedMeta, keyof TNewMeta> & TNewMeta,
+    MergeContractMeta<TSharedMeta, TNewMeta>,
     TSharedHeaders,
     TPathPrefix
   > {
     return new ContractGroup({
       namespace: this._namespace,
-      meta: { ...this._meta, ...meta } as unknown as OmitMetaKeys<
-        TSharedMeta,
-        keyof TNewMeta
-      > &
-        TNewMeta,
+      meta: mergeContractMeta(this._meta, meta),
       responses: this._responses,
       headers: this._headers,
       pathPrefix: this._pathPrefix,

package/src/contracts/metadata.ts

@@ -0,0 +1,20 @@
+import type { ContractMeta, MergeContractMeta } from "./types.js";
+
+export function mergeContractMeta<
+  TCurrent extends ContractMeta,
+  TNext extends ContractMeta,
+>(current: TCurrent, next: TNext): MergeContractMeta<TCurrent, TNext> {
+  const metadata: ContractMeta = {
+    ...current,
+    ...next,
+  };
+
+  if (next.openapi !== undefined) {
+    metadata.openapi = {
+      ...current.openapi,
+      ...next.openapi,
+    };
+  }
+
+  return metadata as MergeContractMeta<TCurrent, TNext>;
+}

package/src/contracts/types.ts

@@ -256,6 +256,45 @@ export type OmitMetaKeys<TMeta, K extends PropertyKey> = {
   [P in keyof TMeta as P extends K ? never : P]: TMeta[P];
 };
 
+type DefinedOpenAPIMeta<T> = [Extract<T, OpenAPIOperationMeta>] extends [never]
+  ? Record<never, never>
+  : Extract<T, OpenAPIOperationMeta>;
+
+type OpenAPIMetaFrom<TMeta extends ContractMeta> = TMeta extends {
+  openapi: infer TOpenAPI;
+}
+  ? DefinedOpenAPIMeta<TOpenAPI>
+  : "openapi" extends keyof TMeta
+    ? NonNullable<TMeta["openapi"]>
+    : Record<never, never>;
+
+/**
+ * Merge contract metadata while preserving accumulated OpenAPI fields.
+ *
+ * Top-level metadata uses last-write-wins semantics. OpenAPI operation
+ * metadata is merged one field deep so `meta({ openapi: ... })` and
+ * `openapi(...)` compose consistently.
+ */
+export type MergeContractMeta<
+  TCurrent extends ContractMeta,
+  TNext extends ContractMeta,
+> = ContractMeta &
+  OmitMetaKeys<TCurrent, keyof TNext> &
+  OmitMetaKeys<TNext, "openapi"> &
+  ("openapi" extends keyof TNext
+    ? TNext extends { openapi: infer TNextOpenAPI }
+      ? TNextOpenAPI extends OpenAPIOperationMeta
+        ? {
+            openapi: Omit<
+              OpenAPIMetaFrom<TCurrent>,
+              keyof OpenAPIMetaFrom<TNext>
+            > &
+              OpenAPIMetaFrom<TNext>;
+          }
+        : { openapi: TNextOpenAPI }
+      : { openapi?: OpenAPIOperationMeta }
+    : Record<never, never>);
+
 /**
  * Plain HTTP contract configuration consumed by server, client, and tooling.
  */

package/src/events/index.ts

@@ -119,15 +119,11 @@ export interface ListenerDef<
 /**
  * Options for `defineListener(...)`.
  */
-export interface DefineListenerOptions<
-  E extends EventDef,
-  Ctx,
-  Name extends string,
-> {
+export interface DefineListenerOptions<E extends EventDef, Ctx> {
   /**
-   * Stable listener name.
+   * Event this listener handles.
    */
-  name: Name;
+  event: E;
   /**
    * Handle a parsed event payload.
    */
@@ -181,9 +177,9 @@ export interface Listeners<Ctx> {
   /**
    * Define a listener with the bound context type.
    */
-  defineListener<E extends EventDef, Name extends string = string>(
-    event: E,
-    options: DefineListenerOptions<E, Ctx, Name>,
+  defineListener<Name extends string, E extends EventDef>(
+    name: Name,
+    options: DefineListenerOptions<E, Ctx>,
   ): ListenerDef<E, Ctx, Name>;
 }
 
@@ -269,17 +265,17 @@ export function defineEvent<
 }
 
 function defineListenerImpl<
-  E extends EventDef,
-  Ctx = unknown,
   Name extends string = string,
+  E extends EventDef = EventDef,
+  Ctx = unknown,
 >(
-  event: E,
-  options: DefineListenerOptions<E, Ctx, Name>,
+  name: Name,
+  options: DefineListenerOptions<E, Ctx>,
 ): ListenerDef<E, Ctx, Name> {
   return {
     kind: "listener",
-    name: options.name,
-    event,
+    name,
+    event: options.event,
     handle: options.handle,
   };
 }
@@ -369,11 +365,11 @@ export function registerListeners<Ctx>(
  */
 export function createListeners<Ctx>(): Listeners<Ctx> {
   return {
-    defineListener<E extends EventDef, Name extends string = string>(
-      event: E,
-      options: DefineListenerOptions<E, Ctx, Name>,
+    defineListener<Name extends string, E extends EventDef>(
+      name: Name,
+      options: DefineListenerOptions<E, Ctx>,
     ): ListenerDef<E, Ctx, Name> {
-      return defineListenerImpl(event, options);
+      return defineListenerImpl(name, options);
     },
   };
 }

package/src/idempotency/index.ts

@@ -644,16 +644,9 @@ export async function runIdempotently<Result>(
       throw new IdempotencyConflictError(reservation);
     }
     case "reserved": {
+      let result: Result;
       try {
-        const result = await options.run();
-        await idempotency.complete({
-          namespace: operation.namespace,
-          key: operation.key,
-          scope: operation.scope,
-          fingerprint: operation.fingerprint,
-          result,
-        });
-        return result;
+        result = await options.run();
       } catch (error) {
         await idempotency.fail({
           namespace: operation.namespace,
@@ -664,6 +657,21 @@ export async function runIdempotently<Result>(
         });
         throw error;
       }
+
+      await idempotency.complete({
+        namespace: operation.namespace,
+        key: operation.key,
+        scope: operation.scope,
+        fingerprint: operation.fingerprint,
+        result,
+      });
+      return result;
+    }
+    default: {
+      const unsupported = reservation as { status?: unknown };
+      throw new Error(
+        `Idempotency port returned unsupported reservation status "${String(unsupported.status)}".`,
+      );
     }
   }
 }

package/src/jobs/index.ts

@@ -1452,10 +1452,15 @@ export function createInlineJobDispatcher<Ctx>(
     payload: InferJobPayload<J>,
     retryEnabled: boolean,
     dispatchOptions: SingleAttemptJobDispatchOptions = {},
+    propagateFailure = false,
   ): Promise<void> {
     const fail = (error: unknown): void => {
-      options.onError?.(error, job);
-      if (!options.onError) throw error;
+      try {
+        options.onError?.(error, job);
+      } catch (observerError) {
+        if (!propagateFailure) throw observerError;
+      }
+      if (propagateFailure || !options.onError) throw error;
     };
 
     let parsed: InferJobPayload<J>;
@@ -1522,7 +1527,7 @@ export function createInlineJobDispatcher<Ctx>(
       job: J,
       payload: InferJobPayload<J>,
       dispatchOptions?: SingleAttemptJobDispatchOptions,
-    ) => run(job, payload, false, dispatchOptions),
+    ) => run(job, payload, false, dispatchOptions, true),
     enumerable: false,
   });
 

package/src/openapi/index.ts

@@ -553,10 +553,13 @@ function addPathParams(
 
   const shape = state.introspector.getShape(contract.pathParams);
   if (!shape) {
-    if (pathKeys.length > 0) {
-      throw new Error(
-        `Unable to introspect pathParams for contract "${contract.name}" at "${contract.path}". OpenAPI path parameters must match the path template.`,
-      );
+    for (const key of pathKeys) {
+      addParameter(operation, {
+        name: key,
+        in: "path",
+        required: true,
+        schema: { type: "string" },
+      });
     }
     return;
   }
@@ -612,14 +615,8 @@ function addQueryParams(
     const originalField = shape[key];
     const optional = state.introspector.isOptional(originalField);
 
-    let description = state.introspector.getDescription(originalField);
-
     const field = originalField;
-
-    // If outer optional didn't have description, check inner type
-    if (!description && optional) {
-      description = state.introspector.getDescription(field);
-    }
+    const description = parameterDescription(field, optional, state);
 
     const paramSchemaRef = schemaToConvertedSchemaRef(
       field,
@@ -656,7 +653,7 @@ function addHeaderParams(
     for (const key of Object.keys(shape)) {
       const originalField = shape[key];
       const optional = state.introspector.isOptional(originalField);
-      const description = state.introspector.getDescription(originalField);
+      const description = parameterDescription(originalField, optional, state);
 
       const paramSchemaRef = schemaToConvertedSchemaRef(
         originalField,
@@ -676,6 +673,21 @@ function addHeaderParams(
   }
 }
 
+function parameterDescription(
+  field: unknown,
+  optional: boolean,
+  state: GeneratorState,
+): string | undefined {
+  return (
+    state.introspector.getDescription(field) ??
+    (optional
+      ? state.introspector.getDescription(
+          state.introspector.unwrapOptional(field),
+        )
+      : undefined)
+  );
+}
+
 /**
  * Add request body from contract to operation
  */

package/src/ports/auth.ts

@@ -36,6 +36,8 @@ export interface AuthSession<User = unknown, Session = unknown> {
  */
 export class AuthUnauthorizedError extends Error {
   readonly code = "UNAUTHORIZED";
+  /** HTTP status used when the server maps this framework error. */
+  readonly status = 401;
 
   constructor(message = "Unauthorized") {
     super(message);

package/src/providers/index.ts

@@ -39,6 +39,7 @@ export {
   parseProviderPackageMetadata,
 } from "./metadata.js";
 export {
+  type AnyProviderConfigSchema,
   type AnyServiceProvider,
   createProvider,
   type InferOutput,

package/src/providers/provider.ts

@@ -240,6 +240,22 @@ export interface ServiceProvider<
   readonly __providedPorts?: ProvidedPorts;
 }
 
+/**
+ * A provider configuration schema whose concrete validation library and input
+ * shape are intentionally erased while its validated output may stay typed.
+ *
+ * Reusable provider packages use this in their named provider return types so
+ * internal Zod schemas do not become part of the package's public API.
+ */
+export type AnyProviderConfigSchema<
+  // biome-ignore lint/suspicious/noExplicitAny: arbitrary provider consumers may erase config output
+  Output = any,
+> = StandardSchemaV1<
+  // biome-ignore lint/suspicious/noExplicitAny: reusable provider return types intentionally erase config input
+  any,
+  Output
+>;
+
 /**
  * Loosely typed service provider.
  *
@@ -250,8 +266,7 @@ export interface ServiceProvider<
  */
 export type AnyServiceProvider = ServiceProvider<
   unknown,
-  // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
-  StandardSchemaV1<any, any>,
+  AnyProviderConfigSchema,
   ProviderPorts,
   // biome-ignore lint/suspicious/noExplicitAny: provider context types are erased at this level
   any,