@beignet/core 0.0.3 → 0.0.5

package/src/openapi/index.ts

@@ -4,7 +4,6 @@
  * OpenAPI 3.1 generation from Beignet contracts
  */
 
-import { type ZodTypeAny, z } from "zod";
 import {
   type AnyContract,
   type ContractLike,
@@ -13,17 +12,26 @@ import {
   parsePathTemplate,
   resolveContract,
   STANDARD_ERROR_RESPONSE_SCHEMA,
-} from "../contracts";
+} from "../contracts/index.js";
+import {
+  comparePathParamsToTemplate,
+  formatPathParamsMismatch,
+} from "../contracts/schema-shape.js";
 import {
   createZodIntrospector,
+  createZodSchemaConverter,
+  type SchemaConverter,
   type SchemaIntrospector,
-} from "./schema-introspector";
+  type SchemaIO,
+} from "./schema-introspector.js";
 
 // Re-export the introspector types for consumers who want custom implementations
 export {
   createZodIntrospector,
+  createZodSchemaConverter,
+  type SchemaConverter,
   type SchemaIntrospector,
-} from "./schema-introspector";
+} from "./schema-introspector.js";
 
 /**
  * OpenAPI 3.1 info object.
@@ -338,6 +346,11 @@ export interface OpenAPIGeneratorOptions {
    * to support other schema libraries.
    */
   schemaIntrospector?: SchemaIntrospector;
+  /**
+   * Schema converters used to turn contract schemas into OpenAPI schemas.
+   * Custom converters run before Beignet's default Zod converter.
+   */
+  schemaConverters?: readonly SchemaConverter[];
 }
 
 /**
@@ -347,10 +360,9 @@ type GeneratorState = {
   components: ComponentsObject;
   jsonMediaType: string;
   introspector: SchemaIntrospector;
+  schemaConverters: readonly SchemaConverter[];
 };
 
-type SchemaIO = "input" | "output";
-
 /**
  * Contract input accepted by the OpenAPI generator.
  */
@@ -392,6 +404,10 @@ export function contractsToOpenAPI(
     components,
     jsonMediaType: options.jsonMediaType ?? "application/json",
     introspector: options.schemaIntrospector ?? createZodIntrospector(),
+    schemaConverters: [
+      ...(options.schemaConverters ?? []),
+      createZodSchemaConverter(),
+    ],
   };
 
   for (const contract of contracts) {
@@ -456,6 +472,7 @@ function addContractToPaths(
   addHeaderParams(contract, operation, state);
   addRequestBody(contract, operation, state);
   addResponses(contract, operation, state);
+  applyOpenAPIOverrides(operation, meta);
 
   // Clean up empty parameters array
   if (operation.parameters?.length === 0) {
@@ -474,6 +491,25 @@ function addContractToPaths(
   pathItem[methodKey] = operation;
 }
 
+function applyOpenAPIOverrides(
+  operation: OperationObject,
+  meta: AnyContract["metadata"]["openapi"] | undefined,
+): void {
+  if (!meta) return;
+
+  for (const parameter of meta.parameters ?? []) {
+    addParameter(operation, parameter);
+  }
+
+  if (meta.requestBody) {
+    operation.requestBody = meta.requestBody;
+  }
+
+  for (const [status, response] of Object.entries(meta.responses ?? {})) {
+    operation.responses[status] = response;
+  }
+}
+
 function addParameter(
   operation: OperationObject,
   parameter: ParameterObject,
@@ -525,20 +561,12 @@ function addPathParams(
     return;
   }
 
-  const shapeKeys = Object.keys(shape);
-  const missingKeys = pathKeys.filter((key) => !shapeKeys.includes(key));
-  const extraKeys = shapeKeys.filter((key) => !pathKeys.includes(key));
+  const { missingKeys, extraKeys } = comparePathParamsToTemplate({
+    pathKeys,
+    shapeKeys: Object.keys(shape),
+  });
   if (missingKeys.length > 0 || extraKeys.length > 0) {
-    const details = [
-      missingKeys.length > 0
-        ? `missing pathParams keys: ${missingKeys.join(", ")}`
-        : undefined,
-      extraKeys.length > 0
-        ? `extra pathParams keys: ${extraKeys.join(", ")}`
-        : undefined,
-    ]
-      .filter(Boolean)
-      .join("; ");
+    const details = formatPathParamsMismatch({ missingKeys, extraKeys });
     throw new Error(
       `Path parameters for contract "${contract.name}" must match "${contract.path}" (${details}).`,
     );
@@ -546,8 +574,8 @@ function addPathParams(
 
   for (const key of pathKeys) {
     const field = shape[key];
-    const paramSchemaRef = zodToSchemaRef(
-      field as ZodTypeAny,
+    const paramSchemaRef = schemaToConvertedSchemaRef(
+      field,
       `${contract.name}_path_${key}`,
       state,
       "input",
@@ -593,8 +621,8 @@ function addQueryParams(
       description = state.introspector.getDescription(field);
     }
 
-    const paramSchemaRef = zodToSchemaRef(
-      field as ZodTypeAny,
+    const paramSchemaRef = schemaToConvertedSchemaRef(
+      field,
       `${contract.name}_query_${key}`,
       state,
       "input",
@@ -630,8 +658,8 @@ function addHeaderParams(
       const optional = state.introspector.isOptional(originalField);
       const description = state.introspector.getDescription(originalField);
 
-      const paramSchemaRef = zodToSchemaRef(
-        originalField as ZodTypeAny,
+      const paramSchemaRef = schemaToConvertedSchemaRef(
+        originalField,
         `${contract.name}_header_${key}`,
         state,
         "input",
@@ -663,8 +691,8 @@ function addRequestBody(
     );
   }
 
-  const schemaRef = zodToSchemaRef(
-    contract.body as ZodTypeAny,
+  const schemaRef = schemaToConvertedSchemaRef(
+    contract.body,
     `${contract.name}_body`,
     state,
     "input",
@@ -889,10 +917,10 @@ function normalizeExampleKey(key: string): string {
 }
 
 /**
- * Convert a Zod schema to a JSON Schema reference, registering it in components
+ * Convert a validation schema to a JSON Schema reference, registering it in components.
  */
-function zodToSchemaRef(
-  schema: ZodTypeAny,
+function schemaToConvertedSchemaRef(
+  schema: unknown,
   nameHint: string,
   state: GeneratorState,
   io: SchemaIO,
@@ -905,14 +933,21 @@ function zodToSchemaRef(
   const schemaName = normalizeSchemaName(nameHint, state);
 
   if (!state.components.schemas[schemaName]) {
-    const jsonSchema = z.toJSONSchema(schema, {
-      target: "draft-2020-12",
-      unrepresentable: "any",
-      io,
-    }) as SchemaObject;
+    const converter = state.schemaConverters.find((candidate) =>
+      candidate.canConvert(schema),
+    );
+
+    if (!converter) {
+      throw new Error(
+        `Unable to convert schema "${nameHint}" to OpenAPI. ` +
+          "Pass a schemaConverters entry to contractsToOpenAPI for this schema library.",
+      );
+    }
 
-    // Remove $schema as it's not needed in OpenAPI
-    delete jsonSchema.$schema;
+    const jsonSchema = converter.toJSONSchema(schema, {
+      nameHint,
+      io,
+    });
 
     state.components.schemas[schemaName] = jsonSchema;
   }
@@ -930,7 +965,7 @@ function schemaToSchemaRef(
     return standardErrorResponseSchemaRef(nameHint, state);
   }
 
-  return zodToSchemaRef(schema as ZodTypeAny, nameHint, state, io);
+  return schemaToConvertedSchemaRef(schema, nameHint, state, io);
 }
 
 function standardErrorResponseSchemaRef(

package/src/openapi/schema-introspector.ts

@@ -1,3 +1,45 @@
+import { type ZodTypeAny, z } from "zod";
+import { getObjectSchemaShape } from "../contracts/schema-shape.js";
+
+export type SchemaIO = "input" | "output";
+
+type ConvertedSchemaObject = Record<string, unknown>;
+
+/**
+ * Context passed to an OpenAPI schema converter.
+ */
+export type SchemaConverterContext = {
+  /**
+   * Whether the schema is documenting request input or response output.
+   */
+  io: SchemaIO;
+  /**
+   * Component name hint Beignet will use when registering the converted schema.
+   */
+  nameHint: string;
+};
+
+/**
+ * Converts a validation schema into an OpenAPI-compatible JSON Schema object.
+ */
+export interface SchemaConverter {
+  /**
+   * Human-readable converter name used in diagnostics.
+   */
+  name: string;
+  /**
+   * Return true when this converter owns the schema value.
+   */
+  canConvert(schema: unknown): boolean;
+  /**
+   * Convert the schema into an OpenAPI-compatible JSON Schema object.
+   */
+  toJSONSchema(
+    schema: unknown,
+    context: SchemaConverterContext,
+  ): ConvertedSchemaObject;
+}
+
 /**
  * Schema introspection adapter.
  *
@@ -31,6 +73,31 @@ export interface SchemaIntrospector {
   unwrapOptional(schema: unknown): unknown;
 }
 
+/**
+ * Create the default schema converter for Zod schemas.
+ */
+export function createZodSchemaConverter(): SchemaConverter {
+  return {
+    name: "zod",
+    canConvert(schema: unknown): boolean {
+      return schema instanceof z.ZodType;
+    },
+    toJSONSchema(
+      schema: unknown,
+      context: SchemaConverterContext,
+    ): ConvertedSchemaObject {
+      const jsonSchema = z.toJSONSchema(schema as ZodTypeAny, {
+        target: "draft-2020-12",
+        unrepresentable: "any",
+        io: context.io,
+      }) as ConvertedSchemaObject;
+
+      delete jsonSchema.$schema;
+      return jsonSchema;
+    },
+  };
+}
+
 /**
  * Create a schema introspector for Zod schemas.
  *
@@ -41,23 +108,7 @@ export interface SchemaIntrospector {
 export function createZodIntrospector(): SchemaIntrospector {
   return {
     getShape(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>;
+      return getObjectSchemaShape(schema);
     },
 
     getDescription(schema: unknown): string | undefined {

package/src/outbox/index.ts

@@ -9,7 +9,7 @@ import {
   type EventPayloadDef,
   type InferEventPayload,
   parseEventPayload,
-} from "../events";
+} from "../events/index.js";
 import {
   getJobRetryDelayMs,
   getJobRetryMaxAttempts,
@@ -17,16 +17,17 @@ import {
   type JobDef,
   parseJobPayload,
   shouldRetryJob,
-} from "../jobs";
-import type { JobDispatcherPort } from "../ports/events";
+} from "../jobs/index.js";
+import type { JobDispatcherPort } from "../ports/events.js";
 import type {
   BufferedDomainEventRecorder,
   DomainEventRecorderPort,
-} from "../ports/unit-of-work";
+} from "../ports/unit-of-work.js";
 import {
+  type BaseProviderInstrumentationEvent,
   createProviderInstrumentation,
   type ProviderInstrumentationTarget,
-} from "../providers";
+} from "../providers/index.js";
 
 /**
  * Value or promise of that value.
@@ -365,6 +366,14 @@ export interface DefineOutboxRegistryInput {
   jobs?: readonly JobDef[];
 }
 
+/**
+ * Correlation fields attached to outbox instrumentation events.
+ */
+export type OutboxInstrumentationContext = Pick<
+  BaseProviderInstrumentationEvent,
+  "requestId" | "traceId" | "spanId" | "parentSpanId" | "traceparent"
+>;
+
 /**
  * Options for draining one outbox batch.
  */
@@ -413,9 +422,14 @@ export interface DrainOutboxOptions {
         now: Date;
       }) => number);
   /**
-   * Optional instrumentation target for retry and dead-letter visibility.
+   * Optional instrumentation target for delivery, retry, and dead-letter
+   * visibility.
    */
   instrumentation?: ProviderInstrumentationTarget;
+  /**
+   * Optional correlation fields attached to outbox instrumentation events.
+   */
+  instrumentationContext?: OutboxInstrumentationContext;
   /**
    * Observer called when delivery fails. Observer failures are ignored so the
    * original delivery failure still controls retry/dead-letter behavior.
@@ -953,6 +967,20 @@ function shouldRetryOutboxMessage(
   });
 }
 
+function outboxInstrumentationDetails(
+  message: ClaimedOutboxMessage,
+  details?: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    attempt: message.attempts,
+    maxAttempts: message.maxAttempts,
+    messageId: message.id,
+    messageKind: message.kind,
+    messageName: message.name,
+    ...details,
+  };
+}
+
 async function deliverOutboxMessage(
   options: DrainOutboxOptions,
   message: ClaimedOutboxMessage,
@@ -1007,6 +1035,13 @@ export async function drainOutbox(
   const batchSize = options.batchSize ?? 100;
   assertPositiveInteger("batchSize", batchSize);
   const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "outbox",
+      watcher: "outbox",
+    },
+  );
+  const jobInstrumentation = createProviderInstrumentation(
     options.instrumentation,
     {
       providerName: "outbox",
@@ -1035,6 +1070,15 @@ export async function drainOutbox(
         claimToken: message.claimToken,
         now,
       });
+      instrumentation.record({
+        type: "outbox",
+        ...options.instrumentationContext,
+        messageId: message.id,
+        messageKind: message.kind,
+        messageName: message.name,
+        status: "delivered",
+        details: outboxInstrumentationDetails(message),
+      });
       result.delivered += 1;
     } catch (error) {
       try {
@@ -1060,34 +1104,55 @@ export async function drainOutbox(
       });
 
       if (deadLetter) {
+        instrumentation.record({
+          type: "outbox",
+          ...options.instrumentationContext,
+          messageId: message.id,
+          messageKind: message.kind,
+          messageName: message.name,
+          status: "deadLettered",
+          details: outboxInstrumentationDetails(message, {
+            error: serializeOutboxError(error),
+          }),
+        });
         if (message.kind === "job") {
-          instrumentation.record({
+          jobInstrumentation.record({
             type: "job",
+            ...options.instrumentationContext,
             jobName: message.name,
             status: "deadLettered",
-            details: {
-              attempt: message.attempts,
-              maxAttempts: message.maxAttempts,
-              messageId: message.id,
+            details: outboxInstrumentationDetails(message, {
               error: serializeOutboxError(error),
-            },
+            }),
           });
         }
         result.deadLettered += 1;
       } else {
+        const retryAt = new Date(now.getTime() + retryDelayMs).toISOString();
+        instrumentation.record({
+          type: "outbox",
+          ...options.instrumentationContext,
+          messageId: message.id,
+          messageKind: message.kind,
+          messageName: message.name,
+          status: "retryScheduled",
+          details: outboxInstrumentationDetails(message, {
+            retryDelayMs,
+            retryAt,
+            error: serializeOutboxError(error),
+          }),
+        });
         if (message.kind === "job") {
-          instrumentation.record({
+          jobInstrumentation.record({
             type: "job",
+            ...options.instrumentationContext,
             jobName: message.name,
             status: "retryScheduled",
-            details: {
-              attempt: message.attempts,
-              maxAttempts: message.maxAttempts,
-              messageId: message.id,
+            details: outboxInstrumentationDetails(message, {
               retryDelayMs,
-              retryAt: new Date(now.getTime() + retryDelayMs).toISOString(),
+              retryAt,
               error: serializeOutboxError(error),
-            },
+            }),
           });
         }
         result.retried += 1;

package/src/ports/audit.ts

@@ -1,4 +1,8 @@
-import { redactValue } from "./redaction";
+import {
+  type ProviderInstrumentationTarget,
+  resolveProviderInstrumentationPort,
+} from "../providers/instrumentation.js";
+import { redactValue } from "./redaction.js";
 
 /**
  * The normalized category of actor that caused application activity.
@@ -111,10 +115,11 @@ export interface ActivityResource {
 /**
  * A normalized audit/activity log entry.
  *
- * Application code usually creates these through an app-owned helper such as
- * `auditEntry(ctx, { action, resource })` so actor, tenant, request ID, and
- * trace ID are copied from context consistently. Durability depends on the
- * `AuditLogPort` implementation.
+ * Application code usually records entries through an audit port wrapped with
+ * `createAmbientAuditLog(...)` from `@beignet/core/server`, which fills
+ * missing actor, tenant, request ID, and trace ID fields from the ambient
+ * request context at record time. Durability depends on the `AuditLogPort`
+ * implementation.
  */
 export interface AuditLogEntry {
   /**
@@ -165,14 +170,18 @@ export interface AuditLogEntry {
 /**
  * Input accepted by `AuditLogPort.record(...)`.
  *
- * `occurredAt` and `outcome` are optional at call sites. Adapters that store
- * audit entries should call `normalizeAuditLogEntry(...)` before persistence or
- * otherwise apply equivalent defaults.
+ * `actor`, `occurredAt`, and `outcome` are optional at call sites. Wrappers
+ * such as `createAmbientAuditLog(...)` fill a missing actor from the ambient
+ * request context. Adapters that store audit entries should call
+ * `normalizeAuditLogEntry(...)` before persistence or otherwise apply
+ * equivalent defaults; entries without an actor normalize to an anonymous
+ * actor.
  */
 export type AuditLogEntryInput = Omit<
   AuditLogEntry,
-  "occurredAt" | "outcome"
+  "actor" | "occurredAt" | "outcome"
 > & {
+  actor?: ActivityActor;
   occurredAt?: Date;
   outcome?: AuditOutcome;
 };
@@ -259,7 +268,7 @@ export function createServiceActor(
 /**
  * Create a system actor descriptor for framework or app-owned background work.
  *
- * Use this for scheduled tasks, scripts, maintenance jobs, and other work that
+ * Use this for schedules, scripts, maintenance jobs, and other work that
  * is not directly caused by a user or external service.
  *
  * @example
@@ -334,13 +343,15 @@ export function createTenant(
  * Fill default audit fields for an input entry.
  *
  * @param entry - Partial audit entry accepted by `AuditLogPort.record(...)`.
- * @returns A complete audit entry with `occurredAt` and `outcome` populated.
+ * @returns A complete audit entry with `actor`, `occurredAt`, and `outcome`
+ * populated. Entries without an actor default to an anonymous actor.
  */
 export function normalizeAuditLogEntry(
   entry: AuditLogEntryInput,
 ): AuditLogEntry {
   return {
     ...entry,
+    actor: entry.actor ?? createAnonymousActor(),
     occurredAt: entry.occurredAt ?? new Date(),
     outcome: entry.outcome ?? "success",
   };
@@ -409,6 +420,104 @@ export function createRedactedAuditLog(
   };
 }
 
+/**
+ * Options for wrapping an audit log with instrumentation emission.
+ */
+export interface InstrumentedAuditLogOptions {
+  /**
+   * Durable audit log to write first.
+   */
+  audit: AuditLogPort;
+  /**
+   * Instrumentation sink, port, or ports object. Pass the app ports object so
+   * the sink (`ports.instrumentation`, then `ports.devtools`) is resolved
+   * lazily on each write and observes provider startup order.
+   */
+  instrumentation?: ProviderInstrumentationTarget;
+  /**
+   * Whether to emit instrumentation events. Defaults to true.
+   */
+  emit?: boolean;
+  /**
+   * Optional app-owned redactor applied after Beignet's audit redaction.
+   */
+  redact?: (entry: AuditLogEntry) => AuditLogEntry;
+}
+
+function prepareInstrumentedEntry(
+  input: AuditLogEntryInput,
+  redact?: (entry: AuditLogEntry) => AuditLogEntry,
+): AuditLogEntry {
+  const redacted = redactAuditLogEntry(normalizeAuditLogEntry(input));
+  return redact ? redact(redacted) : redacted;
+}
+
+function auditSummary(entry: AuditLogEntry): string {
+  const resource = entry.resource?.id
+    ? `${entry.resource.type}:${entry.resource.id}`
+    : entry.resource?.type;
+  const outcome = entry.outcome === "failure" ? "failed" : "succeeded";
+  return resource
+    ? `${entry.action} ${outcome} for ${resource}`
+    : `${entry.action} ${outcome}`;
+}
+
+/**
+ * Wrap an audit log so durable audit writes also appear in instrumentation
+ * sinks such as devtools.
+ *
+ * Instrumentation failures are ignored so audit persistence remains the
+ * source of truth.
+ *
+ * @example
+ * ```ts
+ * const audit = createInstrumentedAuditLog({
+ *   audit: createDrizzleAuditLog(db),
+ *   instrumentation: ports,
+ * });
+ * ```
+ */
+export function createInstrumentedAuditLog(
+  options: InstrumentedAuditLogOptions,
+): AuditLogPort {
+  return {
+    async record(input) {
+      const entry = prepareInstrumentedEntry(input, options.redact);
+
+      await options.audit.record(entry);
+
+      if (options.emit === false) return;
+
+      const port = resolveProviderInstrumentationPort(options.instrumentation);
+      if (!port) return;
+
+      try {
+        port.record({
+          type: "custom",
+          watcher: "audit",
+          name: entry.action,
+          label: "Audit",
+          summary: auditSummary(entry),
+          requestId: entry.requestId,
+          traceId: entry.traceId,
+          details: {
+            action: entry.action,
+            actor: entry.actor,
+            tenant: entry.tenant,
+            resource: entry.resource,
+            outcome: entry.outcome,
+            message: entry.message,
+            metadata: entry.metadata,
+            occurredAt: entry.occurredAt.toISOString(),
+          },
+        });
+      } catch {
+        // Instrumentation is an observer; durable audit writes must not depend on it.
+      }
+    },
+  };
+}
+
 /**
  * Create an in-memory audit log for tests and local examples.
  *