@beignet/core 0.0.36 → 0.0.38

package/src/client/client.ts

@@ -12,6 +12,7 @@ import {
   type StandardSchemaV1,
 } from "../contracts/index.js";
 import { isErrorResponseBody, SchemaValidationError } from "../errors/index.js";
+import { encodeQueryValue } from "../query-codec.js";
 import type {
   CallArgs,
   ClientConfig,
@@ -948,13 +949,7 @@ export class Endpoint<
       const normalizedQuery = queryToSerialize ?? query;
       for (const [key, value] of Object.entries(normalizedQuery)) {
         if (value !== undefined && value !== null) {
-          if (Array.isArray(value)) {
-            for (const v of value) {
-              params.append(key, this.serializeQueryParam(key, v));
-            }
-          } else {
-            params.append(key, this.serializeQueryParam(key, value));
-          }
+          params.append(key, this.serializeQueryParam(key, value));
         }
       }
       const queryString = params.toString();
@@ -972,31 +967,11 @@ export class Endpoint<
   }
 
   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.
-      }
+    try {
+      return encodeQueryValue(value);
+    } catch {
+      throw this.invalidQueryParam(key, "contains a non-serializable value");
     }
-
-    throw this.invalidQueryParam(key, "contains a non-serializable value");
   }
 
   private invalidQueryParam(key: string, reason: string): ContractError {

package/src/contracts/contract-builder.ts

@@ -5,6 +5,11 @@ import {
   mergeCatalogErrors,
   responsesFromErrors,
 } from "./catalog-errors.js";
+import {
+  assertValidContractDeprecation,
+  assertValidContractLifecycle,
+  type ContractDeprecationMeta,
+} from "./lifecycle.js";
 import { mergeContractMeta } from "./metadata.js";
 import type { OpenAPIOperationMeta } from "./openapi-meta.js";
 import { parsePathTemplate } from "./path-template.js";
@@ -68,6 +73,7 @@ export class ContractBuilder<
       THeaders
     >,
   ) {
+    assertValidContractLifecycle(config);
     if (config.body && !methodSupportsRequestBody(config.method)) {
       throw new Error(
         `Request bodies are not supported for ${config.method} contracts. Use POST, PUT, or PATCH for contract request bodies.`,
@@ -457,6 +463,38 @@ export class ContractBuilder<
     });
   }
 
+  /**
+   * Mark this contract as deprecated for external clients.
+   */
+  deprecated<const TDeprecation extends ContractDeprecationMeta>(
+    deprecation: TDeprecation,
+  ): ContractBuilder<
+    TMethod,
+    TPathParams,
+    TQuery,
+    TBody,
+    THeaders,
+    TResponses,
+    MergeContractMeta<TMeta, { deprecation: TDeprecation }>,
+    TPath
+  > {
+    assertValidContractDeprecation(deprecation, this.name);
+    return new ContractBuilder({
+      kind: this.kind,
+      name: this.name,
+      namespace: this.namespace,
+      localName: this.localName,
+      method: this.method,
+      path: this._path,
+      pathParams: this._pathParams,
+      query: this._query,
+      headers: this._headers,
+      body: this._body,
+      responses: this._responses,
+      metadata: mergeContractMeta(this._meta, { deprecation }),
+    });
+  }
+
   /**
    * Merge OpenAPI operation metadata into this contract.
    */

package/src/contracts/contract-group.ts

@@ -5,6 +5,10 @@ import {
   responsesFromErrors,
 } from "./catalog-errors.js";
 import { ContractBuilder } from "./contract-builder.js";
+import {
+  assertValidContractDeprecation,
+  type ContractDeprecationMeta,
+} from "./lifecycle.js";
 import { mergeContractMeta } from "./metadata.js";
 import { parsePathTemplate } from "./path-template.js";
 import type {
@@ -164,6 +168,27 @@ export class ContractGroup<
     });
   }
 
+  /**
+   * Mark every contract created from this group as deprecated.
+   */
+  deprecated<const TDeprecation extends ContractDeprecationMeta>(
+    deprecation: TDeprecation,
+  ): ContractGroup<
+    TSharedResponses,
+    MergeContractMeta<TSharedMeta, { deprecation: TDeprecation }>,
+    TSharedHeaders,
+    TPathPrefix
+  > {
+    assertValidContractDeprecation(deprecation, this._namespace || "group");
+    return new ContractGroup({
+      namespace: this._namespace,
+      meta: mergeContractMeta(this._meta, { deprecation }),
+      responses: this._responses,
+      headers: this._headers,
+      pathPrefix: this._pathPrefix,
+    });
+  }
+
   /**
    * Add shared route-owned response schemas to contracts created from this group.
    *

package/src/contracts/index.ts

@@ -35,6 +35,14 @@ export {
   type ResolveContract,
   resolveContract,
 } from "./contract-like.js";
+/**
+ * Contract lifecycle metadata and errors.
+ */
+export {
+  type ContractDeprecationMeta,
+  ContractLifecycleError,
+  type ContractLifecycleFindingCode,
+} from "./lifecycle.js";
 /**
  * OpenAPI operation metadata type.
  */

package/src/contracts/lifecycle.ts

@@ -0,0 +1,236 @@
+import type { HttpContractConfig } from "./types.js";
+
+/**
+ * Lifecycle metadata for an HTTP contract that external clients should stop
+ * using.
+ */
+export type ContractDeprecationMeta = {
+  /** UTC ISO 8601 timestamp when the contract became deprecated. */
+  since: string;
+  /** Optional human-readable explanation. */
+  reason?: string;
+  /** UTC ISO 8601 timestamp after which the contract may stop being served. */
+  sunset?: string;
+  /** URI reference for the preferred replacement operation. */
+  replacement?: string;
+  /** Absolute HTTP(S) URL with migration or deprecation documentation. */
+  documentation?: string;
+};
+
+/** Stable code identifying invalid lifecycle or operation metadata. */
+export type ContractLifecycleFindingCode =
+  | "INVALID_DEPRECATION_SINCE"
+  | "INVALID_DEPRECATION_SUNSET"
+  | "DEPRECATION_SUNSET_BEFORE_SINCE"
+  | "INVALID_DEPRECATION_REASON"
+  | "INVALID_DEPRECATION_REPLACEMENT"
+  | "INVALID_DEPRECATION_DOCUMENTATION"
+  | "INVALID_OPERATION_ID";
+
+/** Error raised when contract lifecycle metadata is malformed. */
+export class ContractLifecycleError extends Error {
+  /** Stable machine-readable finding code. */
+  readonly code: ContractLifecycleFindingCode;
+  /** Name of the invalid contract, or the group label during group setup. */
+  readonly contract: string;
+
+  constructor(args: {
+    code: ContractLifecycleFindingCode;
+    contract: string;
+    message: string;
+  }) {
+    super(args.message);
+    this.name = "ContractLifecycleError";
+    this.code = args.code;
+    this.contract = args.contract;
+  }
+}
+
+const ISO_8601_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+const INVALID_URI_REFERENCE_CHARACTERS = /[\s<>"\\]/;
+const INVALID_PERCENT_ENCODING = /%(?![0-9A-Fa-f]{2})/;
+
+function parseUtcTimestamp(value: string): number | undefined {
+  if (!ISO_8601_UTC.test(value)) return undefined;
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)) return undefined;
+
+  const canonical = new Date(timestamp).toISOString();
+  if (value !== canonical && value !== canonical.replace(".000Z", "Z")) {
+    return undefined;
+  }
+
+  return timestamp;
+}
+
+function assertNonEmptyOptionalString(args: {
+  value: unknown;
+  field: "reason" | "replacement";
+  code: ContractLifecycleFindingCode;
+  contract: string;
+}): string | undefined {
+  if (args.value === undefined) return undefined;
+  if (typeof args.value !== "string" || args.value.trim().length === 0) {
+    throw new ContractLifecycleError({
+      code: args.code,
+      contract: args.contract,
+      message: `Contract "${args.contract}" deprecation ${args.field} must be a non-empty string.`,
+    });
+  }
+  return args.value;
+}
+
+/** Validate deprecation metadata supplied by builders or raw contract configs. */
+export function assertValidContractDeprecation(
+  deprecation: unknown,
+  contract: string,
+): asserts deprecation is ContractDeprecationMeta {
+  if (typeof deprecation !== "object" || deprecation === null) {
+    throw new ContractLifecycleError({
+      code: "INVALID_DEPRECATION_SINCE",
+      contract,
+      message: `Contract "${contract}" deprecation metadata must include a valid "since" timestamp.`,
+    });
+  }
+
+  const metadata = deprecation as Record<string, unknown>;
+  const since =
+    typeof metadata.since === "string"
+      ? parseUtcTimestamp(metadata.since)
+      : undefined;
+  if (since === undefined) {
+    throw new ContractLifecycleError({
+      code: "INVALID_DEPRECATION_SINCE",
+      contract,
+      message: `Contract "${contract}" deprecation "since" must be a valid UTC ISO 8601 timestamp such as 2026-07-11T00:00:00Z.`,
+    });
+  }
+
+  let sunset: number | undefined;
+  if (metadata.sunset !== undefined) {
+    sunset =
+      typeof metadata.sunset === "string"
+        ? parseUtcTimestamp(metadata.sunset)
+        : undefined;
+    if (sunset === undefined) {
+      throw new ContractLifecycleError({
+        code: "INVALID_DEPRECATION_SUNSET",
+        contract,
+        message: `Contract "${contract}" deprecation "sunset" must be a valid UTC ISO 8601 timestamp.`,
+      });
+    }
+    if (sunset < since) {
+      throw new ContractLifecycleError({
+        code: "DEPRECATION_SUNSET_BEFORE_SINCE",
+        contract,
+        message: `Contract "${contract}" deprecation "sunset" must not be earlier than "since".`,
+      });
+    }
+  }
+
+  assertNonEmptyOptionalString({
+    value: metadata.reason,
+    field: "reason",
+    code: "INVALID_DEPRECATION_REASON",
+    contract,
+  });
+  const replacement = assertNonEmptyOptionalString({
+    value: metadata.replacement,
+    field: "replacement",
+    code: "INVALID_DEPRECATION_REPLACEMENT",
+    contract,
+  });
+  let replacementIsValid = true;
+  if (replacement) {
+    try {
+      new URL(replacement, "https://beignet.invalid");
+    } catch {
+      replacementIsValid = false;
+    }
+  }
+  if (
+    replacement &&
+    (!replacementIsValid ||
+      INVALID_URI_REFERENCE_CHARACTERS.test(replacement) ||
+      INVALID_PERCENT_ENCODING.test(replacement))
+  ) {
+    throw new ContractLifecycleError({
+      code: "INVALID_DEPRECATION_REPLACEMENT",
+      contract,
+      message: `Contract "${contract}" deprecation "replacement" must be a valid URI reference without whitespace.`,
+    });
+  }
+
+  if (metadata.documentation !== undefined) {
+    let documentation: URL | undefined;
+    if (typeof metadata.documentation === "string") {
+      try {
+        documentation = new URL(metadata.documentation);
+      } catch {
+        documentation = undefined;
+      }
+    }
+    if (
+      !documentation ||
+      (documentation.protocol !== "http:" &&
+        documentation.protocol !== "https:") ||
+      INVALID_URI_REFERENCE_CHARACTERS.test(metadata.documentation as string)
+    ) {
+      throw new ContractLifecycleError({
+        code: "INVALID_DEPRECATION_DOCUMENTATION",
+        contract,
+        message: `Contract "${contract}" deprecation "documentation" must be an absolute HTTP(S) URL.`,
+      });
+    }
+  }
+}
+
+/** Return and validate the operation ID used by OpenAPI and route registries. */
+export function getContractOperationId(
+  contract: Pick<HttpContractConfig, "name" | "metadata">,
+): string {
+  const operationId = contract.metadata.openapi?.operationId ?? contract.name;
+  if (
+    typeof operationId !== "string" ||
+    operationId.trim().length === 0 ||
+    operationId !== operationId.trim()
+  ) {
+    throw new ContractLifecycleError({
+      code: "INVALID_OPERATION_ID",
+      contract: contract.name,
+      message: `Contract "${contract.name}" operationId must be a non-empty string without surrounding whitespace.`,
+    });
+  }
+  return operationId;
+}
+
+/** Validate lifecycle metadata on a complete contract definition. */
+export function assertValidContractLifecycle(
+  contract: Pick<HttpContractConfig, "name" | "metadata">,
+): void {
+  getContractOperationId(contract);
+  const deprecation = contract.metadata.deprecation;
+  if (deprecation !== undefined) {
+    assertValidContractDeprecation(deprecation, contract.name);
+  }
+}
+
+/** Build standards-based HTTP response headers for a deprecated contract. */
+export function contractLifecycleResponseHeaders(
+  contract: Pick<HttpContractConfig, "name" | "metadata">,
+): Record<string, string> {
+  const deprecation = contract.metadata.deprecation;
+  if (deprecation === undefined) return {};
+  assertValidContractDeprecation(deprecation, contract.name);
+
+  const headers: Record<string, string> = {
+    Deprecation: `@${Math.floor(Date.parse(deprecation.since) / 1000)}`,
+  };
+  if (deprecation.sunset) {
+    headers.Sunset = new Date(deprecation.sunset).toUTCString();
+  }
+  if (deprecation.documentation) {
+    headers.Link = `<${deprecation.documentation}>; rel="deprecation"`;
+  }
+  return headers;
+}

package/src/contracts/types.ts

@@ -1,5 +1,6 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { IdempotencyMeta } from "../idempotency/index.js";
+import type { ContractDeprecationMeta } from "./lifecycle.js";
 import type { OpenAPIOperationMeta } from "./openapi-meta.js";
 import type { RateLimitMeta } from "./rate-limit.js";
 
@@ -228,6 +229,10 @@ export type ContractMeta = {
    * OpenAPI operation metadata.
    */
   openapi?: OpenAPIOperationMeta;
+  /**
+   * External API lifecycle metadata for a deprecated contract.
+   */
+  deprecation?: ContractDeprecationMeta;
   /**
    * Optional rate limit configuration for this contract.
    *

package/src/error-reporting/index.ts

@@ -4,6 +4,18 @@
  * Provider-neutral error reporting primitives for Beignet applications.
  */
 
+import { type RedactionOptions, redactValue } from "../ports/redaction.js";
+import {
+  DEFAULT_ERROR_REPORTING_TIMEOUT_MS,
+  errorReportingObserverTimeout,
+  runErrorReportingOperation,
+} from "./internal.js";
+
+export {
+  DEFAULT_ERROR_REPORTING_TIMEOUT_MS,
+  ErrorReportingTimeoutError,
+} from "./internal.js";
+
 type MaybePromise<T> = T | Promise<T>;
 
 /**
@@ -67,6 +79,33 @@ export type ErrorReportOptions = {
   traceparent?: string;
 };
 
+/**
+ * Arguments accepted by `tryReportException(...)`.
+ */
+export interface TryReportExceptionOptions {
+  /** Reporter that owns the capture. Omit it to make reporting a no-op. */
+  reporter?: ErrorReporterPort | ErrorReporterResolver;
+  /** Original application or infrastructure error. */
+  error: unknown;
+  /** Structured metadata attached to the report. */
+  reportOptions?: ErrorReportOptions;
+  /**
+   * Maximum time allowed for capture and, separately, the failure observer.
+   * Set to `false` only when the reporting implementation is intentionally
+   * unbounded.
+   *
+   * @default 1000
+   */
+  timeoutMs?: number | false;
+  /**
+   * Observer for reporter failures. Observer failures are also isolated.
+   */
+  onReporterError?: (args: {
+    error: unknown;
+    reportingError: unknown;
+  }) => MaybePromise<void>;
+}
+
 /**
  * Result returned by a reporting provider after capture.
  */
@@ -102,6 +141,11 @@ export type ErrorReporterPort = {
   flush(options?: ErrorReporterFlushOptions): Promise<boolean>;
 };
 
+/** Lazy reporter resolver evaluated inside the best-effort capture deadline. */
+export type ErrorReporterResolver = () => MaybePromise<
+  ErrorReporterPort | undefined
+>;
+
 /**
  * Captured exception stored by `createMemoryErrorReporter(...)`.
  */
@@ -252,6 +296,73 @@ export function reportMessage(
   return reporter.captureMessage(message, options);
 }
 
+/**
+ * Best-effort exception capture for runtime boundaries.
+ *
+ * Missing reporters, reporter failures, and reporter-failure observer errors
+ * resolve to `undefined` so diagnostics cannot replace application behavior.
+ */
+export async function tryReportException(
+  options: TryReportExceptionOptions,
+): Promise<ErrorReportResult | undefined> {
+  const reporterSource = options.reporter;
+  if (!reporterSource) return undefined;
+
+  const timeoutMs = options.timeoutMs ?? DEFAULT_ERROR_REPORTING_TIMEOUT_MS;
+
+  try {
+    return await runErrorReportingOperation(async () => {
+      const reporter =
+        typeof reporterSource === "function"
+          ? await reporterSource()
+          : reporterSource;
+      if (!reporter) return undefined;
+      return reporter.captureException(options.error, options.reportOptions);
+    }, timeoutMs);
+  } catch (reportingError) {
+    try {
+      if (options.onReporterError) {
+        await runErrorReportingOperation(
+          () =>
+            options.onReporterError?.({
+              error: options.error,
+              reportingError,
+            }),
+          errorReportingObserverTimeout(timeoutMs),
+        );
+      }
+    } catch {
+      // Reporter failure observers must not replace application behavior.
+    }
+    return undefined;
+  }
+}
+
+/**
+ * Redact structured error-report metadata with Beignet's shared sensitive-key
+ * rules. The original exception is intentionally not part of this operation.
+ */
+export function redactErrorReportOptions(
+  options: ErrorReportOptions,
+  redactionOptions: RedactionOptions = {},
+): ErrorReportOptions {
+  return {
+    ...options,
+    user: options.user
+      ? redactValue(options.user, redactionOptions)
+      : options.user,
+    tags: options.tags
+      ? redactValue(options.tags, redactionOptions)
+      : options.tags,
+    contexts: options.contexts
+      ? redactValue(options.contexts, redactionOptions)
+      : options.contexts,
+    extra: options.extra
+      ? redactValue(options.extra, redactionOptions)
+      : options.extra,
+  };
+}
+
 function withAmbientState(
   port: MemoryErrorReporterPort,
   options: ErrorReportOptions | undefined,

package/src/error-reporting/internal.ts

@@ -0,0 +1,47 @@
+type MaybePromise<T> = T | Promise<T>;
+
+export const DEFAULT_ERROR_REPORTING_TIMEOUT_MS = 1000;
+
+export class ErrorReportingTimeoutError extends Error {
+  readonly code = "ERROR_REPORTING_TIMEOUT" as const;
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number) {
+    super(`Error reporting timed out after ${timeoutMs}ms.`);
+    this.name = "ErrorReportingTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+export function errorReportingObserverTimeout(
+  timeoutMs: number | false,
+): number | false {
+  return timeoutMs === false || (Number.isFinite(timeoutMs) && timeoutMs > 0)
+    ? timeoutMs
+    : DEFAULT_ERROR_REPORTING_TIMEOUT_MS;
+}
+
+export async function runErrorReportingOperation<T>(
+  operation: () => MaybePromise<T>,
+  timeoutMs: number | false = DEFAULT_ERROR_REPORTING_TIMEOUT_MS,
+): Promise<T> {
+  if (timeoutMs === false) return operation();
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new TypeError("Error reporting timeoutMs must be a positive number.");
+  }
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(operation),
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(
+          () => reject(new ErrorReportingTimeoutError(timeoutMs)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout);
+  }
+}

package/src/events/index.ts

@@ -1,6 +1,10 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { runWithResolvedTracingContext } from "../tracing/execution.js";
-import type { TracingPort } from "../tracing/index.js";
+import {
+  parseTraceCarrier,
+  type TraceCarrier,
+  type TracingPort,
+} from "../tracing/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -58,6 +62,12 @@ export interface EventDef<
 export type InferEventPayload<E extends EventPayloadDef> =
   E["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
 
+/** Metadata propagated with an event delivery. */
+export interface EventPublishOptions {
+  /** Versioned trace context captured by the event producer. */
+  trace?: TraceCarrier;
+}
+
 /**
  * Options for `defineEvent(...)`.
  */
@@ -140,13 +150,17 @@ export interface EventBusLike {
   publish<E extends EventPayloadDef>(
     event: E,
     payload: InferEventPayload<E>,
+    options?: EventPublishOptions,
   ): MaybePromise<void>;
   /**
    * Subscribe to an event and return an unsubscribe function.
    */
   subscribe<E extends EventPayloadDef>(
     event: E,
-    handler: (payload: InferEventPayload<E>) => MaybePromise<void>,
+    handler: (
+      payload: InferEventPayload<E>,
+      options?: EventPublishOptions,
+    ) => MaybePromise<void>,
   ): () => void;
 }
 
@@ -299,9 +313,10 @@ export async function publishEvent<E extends EventPayloadDef>(
   eventBus: EventBusLike,
   event: E,
   payload: InferEventPayload<E>,
+  options?: EventPublishOptions,
 ): Promise<void> {
   const parsed = await parseEventPayload(event, payload);
-  await eventBus.publish(event, parsed);
+  await eventBus.publish(event, parsed, options);
 }
 
 /**
@@ -316,7 +331,7 @@ export function registerListeners<Ctx>(
   options: RegisterListenersOptions<Ctx> = {},
 ): () => void {
   const unsubscribes = listeners.map((listener) =>
-    eventBus.subscribe(listener.event, async (rawPayload) => {
+    eventBus.subscribe(listener.event, async (rawPayload, publishOptions) => {
       try {
         const payload = await parseEventPayload(listener.event, rawPayload);
         const traceAttributes = {
@@ -330,6 +345,7 @@ export function registerListeners<Ctx>(
             name: `beignet.listener ${listener.name}`,
             type: "listener",
             kind: "consumer",
+            parent: parseTraceCarrier(publishOptions?.trace),
             attributes: traceAttributes,
             metricAttributes: traceAttributes,
           },