@beignet/core 0.0.30 → 0.0.32

package/src/testing/index.ts

@@ -66,6 +66,7 @@ import type {
 } from "../providers/provider.js";
 import { createMemorySearch, type MemorySearchPort } from "../search/index.js";
 import { createAmbientAuditLog } from "../server/audit-context.js";
+import { loadProviderConfig } from "../server/providers/loadProviderConfig.js";
 import {
   clearActiveRequestContext,
   enterActiveRequestContext,
@@ -377,8 +378,10 @@ export function createTestPorts<
   const errorReporter = createMemoryErrorReporter();
   const flags = createMemoryFlags();
   const { jobs, dispatchedJobs } = createRecordingJobDispatcher();
-  const idempotency = createMemoryIdempotencyStore();
   const ids = options.ids ?? createUuidIdGenerator();
+  const idempotency = createMemoryIdempotencyStore({
+    now: () => clock.now(),
+  });
   const logger = createNoopLogger();
   const locks = createMemoryLocks({
     now: () => clock.now(),
@@ -386,7 +389,10 @@ export function createTestPorts<
   });
   const mailer = createMemoryMailer();
   const notifications = createMemoryNotificationPort();
-  const outbox = createMemoryOutbox();
+  const outbox = createMemoryOutbox({
+    id: () => ids.nextId(),
+    now: () => clock.now(),
+  });
   const payments = createMemoryPayments();
   const rateLimit = createMemoryRateLimiter();
   const search = createMemorySearch();
@@ -983,6 +989,12 @@ function createUnboundPortGuard<Ports extends AnyPorts>(ports: Ports): Ports {
  * Options for `installProviderForTest(...)`.
  */
 export interface InstallProviderForTestOptions {
+  /**
+   * Environment variables used to resolve the provider's config through the
+   * same loader the server uses (including the provider's `overrides`).
+   * Ignored when `config` is passed explicitly.
+   */
+  env?: Record<string, string | undefined>;
   /**
    * Base app ports visible to provider setup, such as `{ devtools }`.
    */
@@ -1047,9 +1059,13 @@ export async function installProviderForTest(
           "Pass createServiceContext to installProviderForTest(...) when the test needs a service context.",
       );
     });
+  const config =
+    options.config !== undefined
+      ? options.config
+      : await loadProviderConfig(provider, options.env ?? {}, {});
   const result = await provider.setup({
     ports: basePorts,
-    config: options.config,
+    config,
     createServiceContext,
   });
   const ports: Record<string, unknown> = { ...basePorts, ...result.ports };

package/src/uploads/index.ts

@@ -452,14 +452,19 @@ export type UploadErrorCode =
   | "INVALID_UPLOAD_BODY";
 
 /**
- * Error thrown for expected upload failures.
+ * Base error for expected upload failures.
+ *
+ * Upload workflows throw one of the specific subclasses, such as
+ * {@link UploadNotFoundError} or {@link UnauthorizedUploadError}. Catch this
+ * base class to handle any expected upload failure; the upload router maps it
+ * to an HTTP response using `code`, `status`, and `details`.
  */
 export class UploadError extends Error {
   readonly code: UploadErrorCode;
   readonly status: number;
   readonly details?: unknown;
 
-  constructor(args: {
+  protected constructor(args: {
     code: UploadErrorCode;
     message: string;
     status?: number;
@@ -473,6 +478,111 @@ export class UploadError extends Error {
   }
 }
 
+/**
+ * Error thrown when an upload name is not registered on the router.
+ */
+export class UploadNotFoundError extends UploadError {
+  declare readonly code: "UPLOAD_NOT_FOUND";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "UPLOAD_NOT_FOUND", status: 404, ...args });
+    this.name = "UploadNotFoundError";
+  }
+}
+
+/**
+ * Error thrown when an upload request targets an unknown upload action.
+ */
+export class InvalidUploadActionError extends UploadError {
+  declare readonly code: "INVALID_UPLOAD_ACTION";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "INVALID_UPLOAD_ACTION", status: 400, ...args });
+    this.name = "InvalidUploadActionError";
+  }
+}
+
+/**
+ * Error thrown when upload metadata fails schema validation.
+ */
+export class InvalidUploadMetadataError extends UploadError {
+  declare readonly code: "INVALID_UPLOAD_METADATA";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "INVALID_UPLOAD_METADATA", status: 422, ...args });
+    this.name = "InvalidUploadMetadataError";
+  }
+}
+
+/**
+ * Error thrown when a file fails upload validation, such as file count,
+ * content type (415), size limits (413), or prepared-file mismatches.
+ */
+export class InvalidUploadFileError extends UploadError {
+  declare readonly code: "INVALID_UPLOAD_FILE";
+
+  constructor(args: { message: string; details?: unknown; status?: number }) {
+    super({
+      code: "INVALID_UPLOAD_FILE",
+      message: args.message,
+      status: args.status ?? 422,
+      details: args.details,
+    });
+    this.name = "InvalidUploadFileError";
+  }
+}
+
+/**
+ * Error thrown when an upload is denied by authorize(...) or lacks
+ * authorization configuration.
+ */
+export class UnauthorizedUploadError extends UploadError {
+  declare readonly code: "UNAUTHORIZED_UPLOAD";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "UNAUTHORIZED_UPLOAD", status: 403, ...args });
+    this.name = "UnauthorizedUploadError";
+  }
+}
+
+/**
+ * Error thrown when a completed upload references a stored object that does
+ * not exist.
+ */
+export class UploadObjectNotFoundError extends UploadError {
+  declare readonly code: "UPLOAD_OBJECT_NOT_FOUND";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "UPLOAD_OBJECT_NOT_FOUND", status: 404, ...args });
+    this.name = "UploadObjectNotFoundError";
+  }
+}
+
+/**
+ * Error thrown when an upload request body exceeds the configured size limit.
+ */
+export class UploadBodyTooLargeError extends UploadError {
+  declare readonly code: "UPLOAD_BODY_TOO_LARGE";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "UPLOAD_BODY_TOO_LARGE", status: 413, ...args });
+    this.name = "UploadBodyTooLargeError";
+  }
+}
+
+/**
+ * Error thrown when an upload request body cannot be parsed or has an
+ * invalid shape.
+ */
+export class InvalidUploadBodyError extends UploadError {
+  declare readonly code: "INVALID_UPLOAD_BODY";
+
+  constructor(args: { message: string; details?: unknown }) {
+    super({ code: "INVALID_UPLOAD_BODY", status: 400, ...args });
+    this.name = "InvalidUploadBodyError";
+  }
+}
+
 /**
  * Define a typed upload workflow.
  */
@@ -507,6 +617,47 @@ export function defineUpload<
   };
 }
 
+/**
+ * Context-bound upload helper factory.
+ */
+export interface Uploads<Ctx> {
+  /**
+   * Define an upload workflow with the bound context type.
+   */
+  defineUpload<
+    const Name extends string,
+    MetadataSchema extends StandardSchema,
+    Result = unknown,
+  >(
+    name: Name,
+    options: DefineUploadOptions<MetadataSchema, Ctx, Result>,
+  ): UploadDef<Name, MetadataSchema, Ctx, Result>;
+}
+
+/**
+ * Create upload helper methods bound to an application context type.
+ *
+ * Call it once in `lib/uploads.ts`:
+ *
+ * ```ts
+ * export const { defineUpload } = createUploads<AppContext>();
+ * ```
+ */
+export function createUploads<Ctx>(): Uploads<Ctx> {
+  return {
+    defineUpload<
+      const Name extends string,
+      MetadataSchema extends StandardSchema,
+      Result = unknown,
+    >(
+      name: Name,
+      options: DefineUploadOptions<MetadataSchema, Ctx, Result>,
+    ): UploadDef<Name, MetadataSchema, Ctx, Result> {
+      return defineUpload(name, options);
+    },
+  };
+}
+
 /**
  * Define a nested upload registry while preserving upload names and metadata
  * types for client code.
@@ -612,9 +763,7 @@ export function createUploadRouter<Ctx>(
       const registered = [...uploads.keys()]
         .map((registeredName) => `"${registeredName}"`)
         .join(", ");
-      throw new UploadError({
-        code: "UPLOAD_NOT_FOUND",
-        status: 404,
+      throw new UploadNotFoundError({
         message: `Upload "${name}" is not registered. Registered uploads: ${registered || "none"}. Upload routes resolve the defineUpload(...) name, not the defineUploads({...}) registry key.`,
       });
     }
@@ -723,9 +872,7 @@ export function createUploadRouter<Ctx>(
           uploadId: file.uploadId,
         });
         if (file.key !== expectedKey) {
-          throw new UploadError({
-            code: "INVALID_UPLOAD_FILE",
-            status: 422,
+          throw new InvalidUploadFileError({
             message: `Uploaded object key does not match upload "${upload.name}".`,
             details: {
               expectedKey,
@@ -735,9 +882,7 @@ export function createUploadRouter<Ctx>(
         }
         const object = await options.storage.stat(file.key);
         if (!object) {
-          throw new UploadError({
-            code: "UPLOAD_OBJECT_NOT_FOUND",
-            status: 404,
+          throw new UploadObjectNotFoundError({
             message: `Uploaded object "${file.key}" was not found.`,
           });
         }
@@ -970,9 +1115,7 @@ function assertUploadContentLengthWithinLimit(
   const actualBytes = Number(contentLength);
   if (!Number.isFinite(actualBytes) || actualBytes < 0) return;
   if (actualBytes > context.maxBytes) {
-    throw new UploadError({
-      code: "UPLOAD_BODY_TOO_LARGE",
-      status: 413,
+    throw new UploadBodyTooLargeError({
       message: `Upload "${context.uploadName}" ${context.action} body is too large.`,
       details: {
         maxBytes: context.maxBytes,
@@ -996,9 +1139,7 @@ async function readLimitedRequestText(
     const text = await request.text();
     const actualBytes = new TextEncoder().encode(text).byteLength;
     if (actualBytes > context.maxBytes) {
-      throw new UploadError({
-        code: "UPLOAD_BODY_TOO_LARGE",
-        status: 413,
+      throw new UploadBodyTooLargeError({
         message: `Upload "${context.uploadName}" ${context.action} body is too large.`,
         details: {
           maxBytes: context.maxBytes,
@@ -1020,9 +1161,7 @@ async function readLimitedRequestText(
       if (result.done) break;
       actualBytes += result.value.byteLength;
       if (actualBytes > context.maxBytes) {
-        throw new UploadError({
-          code: "UPLOAD_BODY_TOO_LARGE",
-          status: 413,
+        throw new UploadBodyTooLargeError({
           message: `Upload "${context.uploadName}" ${context.action} body is too large.`,
           details: {
             maxBytes: context.maxBytes,
@@ -1052,9 +1191,7 @@ async function readJsonBody(
     return JSON.parse(await readLimitedRequestText(request, context));
   } catch (error) {
     if (error instanceof UploadError) throw error;
-    throw new UploadError({
-      code: "INVALID_UPLOAD_BODY",
-      status: 400,
+    throw new InvalidUploadBodyError({
       message: `Upload "${context.uploadName}" ${context.action} body must be valid JSON.`,
     });
   }
@@ -1115,9 +1252,7 @@ function parsePrepareInput(
     requireCompletedFileFields: false,
   });
   if (issues.length > 0) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_BODY",
-      status: 400,
+    throw new InvalidUploadBodyError({
       message: `Upload "${uploadName}" prepare body is invalid.`,
       details: { issues },
     });
@@ -1133,9 +1268,7 @@ function parseCompleteInput(
     requireCompletedFileFields: true,
   });
   if (issues.length > 0) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_BODY",
-      status: 400,
+    throw new InvalidUploadBodyError({
       message: `Upload "${uploadName}" complete body is invalid.`,
       details: { issues },
     });
@@ -1150,9 +1283,7 @@ async function parseMetadata<U extends UploadDef>(
   const result = await upload.metadata["~standard"].validate(input);
 
   if (result.issues?.length) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_METADATA",
-      status: 422,
+    throw new InvalidUploadMetadataError({
       message: `Invalid metadata for upload "${upload.name}".`,
       details: { issues: result.issues },
     });
@@ -1171,9 +1302,7 @@ function assertFiles(
 ): void {
   const maxFiles = upload.file.maxFiles ?? 1;
   if (files.length === 0 || files.length > maxFiles) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_FILE",
-      status: 422,
+    throw new InvalidUploadFileError({
       message: `Upload "${upload.name}" requires between 1 and ${maxFiles} file${maxFiles === 1 ? "" : "s"}.`,
       details: { fileCount: files.length, maxFiles },
     });
@@ -1181,9 +1310,7 @@ function assertFiles(
 
   for (const file of files) {
     if (!file.name || !file.contentType || !Number.isFinite(file.size)) {
-      throw new UploadError({
-        code: "INVALID_UPLOAD_FILE",
-        status: 422,
+      throw new InvalidUploadFileError({
         message: `Upload "${upload.name}" received invalid file metadata.`,
         details: { file },
       });
@@ -1193,8 +1320,7 @@ function assertFiles(
       upload.file.contentTypes?.length &&
       !upload.file.contentTypes.includes(file.contentType)
     ) {
-      throw new UploadError({
-        code: "INVALID_UPLOAD_FILE",
+      throw new InvalidUploadFileError({
         status: 415,
         message: `Upload "${upload.name}" does not accept "${file.contentType}".`,
         details: {
@@ -1208,8 +1334,7 @@ function assertFiles(
       upload.file.maxSizeBytes !== undefined &&
       file.size > upload.file.maxSizeBytes
     ) {
-      throw new UploadError({
-        code: "INVALID_UPLOAD_FILE",
+      throw new InvalidUploadFileError({
         status: 413,
         message: `Upload "${upload.name}" exceeds the maximum file size.`,
         details: {
@@ -1228,9 +1353,7 @@ async function assertAuthorized<Metadata, Ctx>(
   if (!upload.authorize) {
     if ((upload.access ?? "protected") === "public") return;
 
-    throw new UploadError({
-      code: "UNAUTHORIZED_UPLOAD",
-      status: 403,
+    throw new UnauthorizedUploadError({
       message: `Upload "${upload.name}" must declare authorize(...) or set access: "public".`,
     });
   }
@@ -1246,9 +1369,7 @@ async function assertAuthorized<Metadata, Ctx>(
       result.allowed === false);
   if (!denied) return;
 
-  throw new UploadError({
-    code: "UNAUTHORIZED_UPLOAD",
-    status: 403,
+  throw new UnauthorizedUploadError({
     message:
       typeof result === "object" && result?.reason
         ? result.reason
@@ -1267,8 +1388,7 @@ function assertStoredObject(
     upload.file.maxSizeBytes !== undefined &&
     object.size > upload.file.maxSizeBytes
   ) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_FILE",
+    throw new InvalidUploadFileError({
       status: 413,
       message: `Uploaded object "${object.key}" exceeds the maximum file size.`,
       details: {
@@ -1279,9 +1399,7 @@ function assertStoredObject(
   }
 
   if (object.size !== file.size) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_FILE",
-      status: 422,
+    throw new InvalidUploadFileError({
       message: `Uploaded object "${object.key}" size does not match the prepared file.`,
       details: {
         expected: file.size,
@@ -1295,9 +1413,7 @@ function assertStoredObject(
     file.contentType &&
     object.contentType !== file.contentType
   ) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_FILE",
-      status: 422,
+    throw new InvalidUploadFileError({
       message: `Uploaded object "${object.key}" content type does not match the prepared file.`,
       details: {
         expected: file.contentType,
@@ -1314,9 +1430,7 @@ function metadataFromFormData(formData: FormData): unknown {
   try {
     return JSON.parse(metadata);
   } catch {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_BODY",
-      status: 400,
+    throw new InvalidUploadBodyError({
       message: "Upload metadata must be valid JSON.",
     });
   }
@@ -1326,9 +1440,7 @@ function filesFromFormData(formData: FormData): File[] {
   const values = [...formData.getAll("file"), ...formData.getAll("files")];
   const files = values.filter((value): value is File => value instanceof File);
   if (files.length === 0) {
-    throw new UploadError({
-      code: "INVALID_UPLOAD_BODY",
-      status: 400,
+    throw new InvalidUploadBodyError({
       message: 'Multipart upload must include at least one "file" field.',
     });
   }

package/src/webhooks/index.ts

@@ -82,6 +82,7 @@ export interface WebhookDef<
   Name extends string = string,
   Events extends WebhookEventSchemas = WebhookEventSchemas,
 > {
+  kind: "webhook";
   name: Name;
   provider?: string;
   events: Events;
@@ -235,6 +236,7 @@ export function defineWebhook<
   if (!name) throw new WebhookOptionsError("Webhook name is required.");
 
   return {
+    kind: "webhook",
     name,
     provider: options.provider,
     events: (options.events ?? {}) as Events,

package/src/domain/events.ts

@@ -1,59 +0,0 @@
-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.
- */
-export type DomainEventDef<
-  Name extends string = string,
-  Payload extends StandardSchema = StandardSchema,
-> = EventDef<Name, Payload>;
-
-/**
- * Infer the payload type from a DomainEventDef.
- *
- * @example
- * ```ts
- * const UserRegistered = defineDomainEvent(
- *   "user.registered",
- *   z.object({
- *     userId: z.string(),
- *     email: z.string().email(),
- *   })
- * );
- *
- * type Payload = InferEventPayload<typeof UserRegistered>;
- * // { userId: string; email: string }
- * ```
- */
-export type { InferEventPayload };
-
-/**
- * Create a new domain event definition.
- *
- * This is a domain-focused alias around `defineEvent(...)` for applications
- * that separate domain events from integration events.
- *
- * @example
- * ```ts
- * const UserRegistered = defineDomainEvent(
- *   "user.registered",
- *   z.object({
- *     userId: z.string(),
- *     email: z.string().email(),
- *   })
- * );
- *
- * type UserRegistered = typeof UserRegistered;
- * ```
- */
-export function defineDomainEvent<
-  Name extends string,
-  Payload extends StandardSchema,
->(name: Name, payload: Payload): DomainEventDef<Name, Payload> {
-  return defineEvent(name, { payload });
-}