better-ship 0.5.0 → 0.7.0

package/dist/tanstack.d.ts

@@ -1,4 +1,4 @@
-import { A as ErrorTable } from "./index-B9Y1hVh6.js";
+import { Y as ErrorTable } from "./index-BStnggQO.js";
 import { Register, RequestServerOptions } from "@tanstack/react-start";
 import { AnyRedirect } from "@tanstack/react-router";
 import { BetterAuthCookies } from "better-auth";
@@ -77,5 +77,12 @@ export declare function createErrorMiddleware<Entries>(options: ErrorMiddlewareO
   toHttpErrorResponse: (cause: unknown) => Response;
 };
 //#endregion
+//#region src/infrastructure/tanstack/last-login-method.d.ts
+/**
+ * Read the method this browser last signed in with from the current request, for the sign-in loader on the server.
+ * Pass `cookieName` only when `integrations.lastLoginMethod.cookieName` is set. Returns `null` when the cookie is absent.
+ */
+export declare function getLastUsedLoginMethod(cookieName?: string): string | null;
+//#endregion
 export type { AuthContext, AuthCookieSource, AuthMiddlewareOptions, AuthSession, ErrorMiddlewareOptions, RequiredAuthContext };
 //# sourceMappingURL=tanstack.d.ts.map

package/dist/tanstack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack.d.ts","names":[],"sources":["../src/infrastructure/tanstack/auth.middleware.ts","../src/infrastructure/tanstack/error.middleware.ts"],"mappings":";;;;;;KASY;WACD;aAAiB;;WACjB;aAAoB;;;;KAInB,oBAAoB,gBAAgB;WACrC,MAAM;WACN,SAAS;;;KAIR,YAAY,gBAAgB,eACpC,oBAAoB;WAET;WACA;;;KAIH,sBAAsB,gBAAgB;WACvC,UAAU,SAAS,qBAAqB;aACtC;eACE,aAAa;QAAW,SAAS;YAAc,QAAQ;;;;;;;;wBAStD,qBAAqB,gBAAgB,aACnD,SAAS,sBAAsB;;;;;;;KChC5B,iBAAiB,qBAAqB;;KAG/B;WACD,UAAU;aAAmB,aAAa;;;;KAIzC,uBAAuB;WACxB,QAAQ,WAAW;;WAEnB,cAAc;;WAEd,UAAU,SAAS,mBAAmB;;;;;;wBAOjC,sBAAsB,SAAS,SAAS,uBAAuB"}
+{"version":3,"file":"tanstack.d.ts","names":[],"sources":["../src/infrastructure/tanstack/auth.middleware.ts","../src/infrastructure/tanstack/error.middleware.ts","../src/infrastructure/tanstack/last-login-method.ts"],"mappings":";;;;;;KASY;WACD;aAAiB;;WACjB;aAAoB;;;;KAInB,oBAAoB,gBAAgB;WACrC,MAAM;WACN,SAAS;;;KAIR,YAAY,gBAAgB,eACpC,oBAAoB;WAET;WACA;;;KAIH,sBAAsB,gBAAgB;WACvC,UAAU,SAAS,qBAAqB;aACtC;eACE,aAAa;QAAW,SAAS;YAAc,QAAQ;;;;;;;;wBAStD,qBAAqB,gBAAgB,aACnD,SAAS,sBAAsB;;;;;;;KChC5B,iBAAiB,qBAAqB;;KAG/B;WACD,UAAU;aAAmB,aAAa;;;;KAIzC,uBAAuB;WACxB,QAAQ,WAAW;;WAEnB,cAAc;;WAEd,UAAU,SAAS,mBAAmB;;;;;;wBAOjC,sBAAsB,SAAS,SAAS,uBAAuB;;;;;;;;;;;;;;;;;;;;wBCpB/D,uBAAuB"}

package/dist/tanstack.js

@@ -1,4 +1,4 @@
-import { A as AppError, C as ValidationError, D as StaleSessionError, a as createLogger, k as AuthenticationError } from "./core-CnwWj4MY.js";
+import { A as StaleSessionError, E as ValidationError, M as AuthenticationError, N as AppError, a as createLogger } from "./core-Cx5SeyKV.js";
 import { z } from "zod";
 import { createMiddleware } from "@tanstack/react-start";
 import { deleteCookie, getRequestHeaders } from "@tanstack/react-start/server";
@@ -210,5 +210,16 @@ function createErrorMiddleware(options) {
 }
 
 //#endregion
-export { createAuthMiddleware, createErrorMiddleware };
+//#region src/infrastructure/tanstack/last-login-method.ts
+const DEFAULT_COOKIE_NAME = "better-auth.last_used_login_method";
+/**
+* Read the method this browser last signed in with from the current request, for the sign-in loader on the server.
+* Pass `cookieName` only when `integrations.lastLoginMethod.cookieName` is set. Returns `null` when the cookie is absent.
+*/
+function getLastUsedLoginMethod(cookieName = DEFAULT_COOKIE_NAME) {
+	return parseCookies(getRequestHeaders().get("cookie") ?? "").get(cookieName) ?? null;
+}
+
+//#endregion
+export { createAuthMiddleware, createErrorMiddleware, getLastUsedLoginMethod };
 //# sourceMappingURL=tanstack.js.map

package/dist/tanstack.js.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack.js","names":["logger"],"sources":["../src/infrastructure/tanstack/auth.middleware.ts","../src/infrastructure/tanstack/resolve-failure.ts","../src/infrastructure/tanstack/http-error-response.ts","../src/infrastructure/tanstack/session-cookies.ts","../src/infrastructure/tanstack/to-error-payload.ts","../src/infrastructure/tanstack/error.middleware.ts"],"sourcesContent":["import { createMiddleware, type Register, type RequestServerOptions } from '@tanstack/react-start'\nimport { getRequestHeaders } from '@tanstack/react-start/server'\nimport { getSessionCookie } from 'better-auth/cookies'\n\nimport { AuthenticationError, StaleSessionError, createLogger } from '@/core'\n\nconst logger = createLogger('auth-middleware')\n\n/** The fields middleware reads; generic callers retain every additional session and user field. */\nexport type AuthSession = {\n  readonly user: { readonly id: string }\n  readonly session: { readonly id: string }\n}\n\n/** Authenticated context retains the application's complete user and session types. */\nexport type RequiredAuthContext<Session extends AuthSession> = {\n  readonly user: Session['user']\n  readonly session: Session['session']\n}\n\n/** Optional authentication supplies both fields together or neither field. */\nexport type AuthContext<Session extends AuthSession> =\n  | RequiredAuthContext<Session>\n  | {\n      readonly user: undefined\n      readonly session: undefined\n    }\n\n/** Select the current request's Better Auth instance from TanStack's registered context. */\nexport type AuthMiddlewareOptions<Session extends AuthSession> = {\n  readonly getAuth: (context: RequestServerOptions<Register, undefined>['context']) => {\n    readonly api: {\n      readonly getSession: (options: { headers: Headers }) => Promise<Session | null>\n    }\n  }\n}\n\n/**\n * Preserve Porte's function and request middleware contracts with application-owned services.\n * Optional lookup failures log once and continue as guests. Required lookup failures propagate.\n */\nexport function createAuthMiddleware<Session extends AuthSession>(\n  options: AuthMiddlewareOptions<Session>,\n) {\n  const extractAuth = createMiddleware({ type: 'function' }).server<AuthContext<Session>>(\n    async ({ next, context }) => {\n      let resolved: Session | null\n      try {\n        resolved = await options.getAuth(context).api.getSession({ headers: getRequestHeaders() })\n      } catch (error) {\n        logger.error('get_session_failed', { error })\n        resolved = null\n      }\n      if (resolved === null)\n        return next<AuthContext<Session>>({ context: { user: undefined, session: undefined } })\n      return next<AuthContext<Session>>({\n        context: { user: resolved.user, session: resolved.session },\n      })\n    },\n  )\n\n  async function resolveRequiredSession(\n    context: RequestServerOptions<Register, undefined>['context'],\n    headers: Headers,\n  ): Promise<Session> {\n    const resolved = await options.getAuth(context).api.getSession({ headers })\n    if (resolved === null) {\n      if (getSessionCookie(headers)) throw new StaleSessionError()\n      throw new AuthenticationError()\n    }\n    return resolved\n  }\n\n  const requireAuth = createMiddleware({ type: 'function' }).server(async ({ next, context }) => {\n    const resolved = await resolveRequiredSession(context, getRequestHeaders())\n    return next<RequiredAuthContext<Session>>({\n      context: { user: resolved.user, session: resolved.session },\n    })\n  })\n  const requireAuthRequest = createMiddleware({ type: 'request' }).server(\n    async ({ request, next, context }) => {\n      const resolved = await resolveRequiredSession(context, request.headers)\n      return next<RequiredAuthContext<Session>>({\n        context: { user: resolved.user, session: resolved.session },\n      })\n    },\n  )\n  return { extractAuth, requireAuth, requireAuthRequest }\n}\n","import { AppError, createLogger, type ErrorTable, type ResolvedError } from '@/core'\nimport type { ErrorPayloadOf } from '@/core'\n\nconst logger = createLogger('error-boundary')\n\n/**\n * Resolve one failure through the table or fall back to the generic replacement, and log it once.\n * Both transport converters call this, so one rule decides the log level: mapped is a warning, unmapped is an error with the cause.\n */\nexport function resolveFailure<Entries>(\n  table: ErrorTable<Entries>,\n  cause: unknown,\n): ResolvedError<ErrorPayloadOf<ErrorTable<Entries>>> {\n  const resolved = table.resolve(cause)\n  if (resolved !== null) {\n    logger.warn('handled_error', {\n      details: { tag: resolved.payload._tag, status: resolved.status },\n    })\n    return resolved\n  }\n  const classification = cause instanceof AppError ? cause.classification : 'unknown'\n  logger.error('unexpected_error', { error: cause, details: { classification } })\n  return table.fallback(cause)\n}\n","import { getReasonPhrase } from 'http-status-codes'\nimport { z } from 'zod'\n\nimport type { ErrorTable, ProblemDetails } from '@/core'\n\nimport { resolveFailure } from './resolve-failure.ts'\n\n// A known delay becomes the header; a null delay sends no header.\nconst RetryAfterSchema = z.object({ retryAfter: z.number() })\n\n/**\n * Build the API route converter for one error table.\n * The body is RFC 9457 problem details; public fields become extension members.\n */\nexport function createHttpErrorResponseConverter<Entries>(table: ErrorTable<Entries>) {\n  return function toHttpErrorResponse(cause: unknown): Response {\n    const { status, payload } = resolveFailure(table, cause)\n    const { _tag, message, ...fields } = payload\n    const body: ProblemDetails = {\n      type: 'about:blank',\n      title: getReasonPhrase(status),\n      detail: message,\n      ...fields,\n    }\n    const headers = new Headers({ 'Content-Type': 'application/problem+json' })\n    const retry = RetryAfterSchema.safeParse(payload)\n    if (retry.success) headers.set('Retry-After', String(retry.data.retryAfter))\n    return Response.json(body, { status, headers })\n  }\n}\n","import { deleteCookie, getRequestHeaders } from '@tanstack/react-start/server'\nimport type { BetterAuthCookies } from 'better-auth'\nimport { parseCookies } from 'better-auth/cookies'\n\ntype AuthCookie = BetterAuthCookies['sessionToken']\ntype DeleteCookieOptions = NonNullable<Parameters<typeof deleteCookie>[1]>\n\n/**\n * Delete the session, session cache, account cache, and remember-me cookies of one instance.\n * Chunks present on the request go too. Names and attributes come from the instance, so custom prefixes and domain cookies clear.\n */\nexport function clearStaleSessionCookies(cookies: BetterAuthCookies): void {\n  const present = [...parseCookies(getRequestHeaders().get('cookie') ?? '').keys()]\n  const definitions = [\n    cookies.sessionToken,\n    cookies.sessionData,\n    cookies.accountData,\n    cookies.dontRememberToken,\n  ]\n  for (const cookie of definitions) {\n    // Better Auth names a chunk `${name}.${index}`, so a missed chunk would resurrect the value.\n    const chunks = present.filter((name) => name.startsWith(`${cookie.name}.`))\n    for (const name of new Set([cookie.name, ...chunks]))\n      deleteCookie(name, deletionOf(cookie.attributes))\n  }\n}\n\nfunction deletionOf(attributes: AuthCookie['attributes']): DeleteCookieOptions {\n  // Better Auth sets `/` and the secure flag at runtime; the types leave both optional.\n  const options: DeleteCookieOptions = {\n    path: attributes.path ?? '/',\n    secure: attributes.secure ?? false,\n  }\n  if (attributes.domain !== undefined) options.domain = attributes.domain\n  return options\n}\n","import { z } from 'zod'\n\nimport { ValidationError, type ErrorPayloadOf, type ErrorTable } from '@/core'\n\nimport { resolveFailure } from './resolve-failure.ts'\n\n// TanStack serializes a validator's issues into `Error.message` as JSON.\nconst SerializedIssuesSchema = z\n  .array(z.object({ message: z.string(), path: z.array(z.union([z.string(), z.number()])) }))\n  .min(1)\n\nfunction reconstructValidationError(cause: unknown): ValidationError | null {\n  if (!(cause instanceof Error)) return null\n  let message: unknown\n  try {\n    message = JSON.parse(cause.message)\n  } catch {\n    return null\n  }\n  const parsed = SerializedIssuesSchema.safeParse(message)\n  return parsed.success ? ValidationError.fromIssues(parsed.data) : null\n}\n\n/**\n * Build the server-function converter for one error table.\n * The result is a plain object, because only own data survives serialization.\n */\nexport function createErrorPayloadConverter<Entries>(table: ErrorTable<Entries>) {\n  return function toErrorPayload(cause: unknown): ErrorPayloadOf<ErrorTable<Entries>> {\n    return resolveFailure(table, reconstructValidationError(cause) ?? cause).payload\n  }\n}\n","import { isNotFound, isRedirect, type AnyRedirect } from '@tanstack/react-router'\nimport { createMiddleware, type Register, type RequestServerOptions } from '@tanstack/react-start'\nimport type { BetterAuthCookies } from 'better-auth'\n\nimport { StaleSessionError, type ErrorTable } from '@/core'\n\nimport { createHttpErrorResponseConverter } from './http-error-response.ts'\nimport { clearStaleSessionCookies } from './session-cookies.ts'\nimport { createErrorPayloadConverter } from './to-error-payload.ts'\n\ntype RequestContext = RequestServerOptions<Register, undefined>['context']\n\n/** The part of a Better Auth instance the boundary reads: its computed cookie definitions. */\nexport type AuthCookieSource = {\n  readonly $context: Promise<{ readonly authCookies: BetterAuthCookies }>\n}\n\n/** The application's error table, its stale-session redirect, and its Better Auth instance. */\nexport type ErrorMiddlewareOptions<Entries> = {\n  readonly errors: ErrorTable<Entries>\n  /** Build the redirect a server function throws for a stale session. */\n  readonly signIn: () => AnyRedirect\n  /** Select the request's Better Auth instance; its cookie definitions say what to clear. */\n  readonly getAuth: (context: RequestContext) => AuthCookieSource\n}\n\n/**\n * Build both transport boundaries from one error table.\n * Register `functionErrorMiddleware` globally. Put `routeErrorMiddleware` first in an API route's `server.middleware`.\n */\nexport function createErrorMiddleware<Entries>(options: ErrorMiddlewareOptions<Entries>) {\n  const toErrorPayload = createErrorPayloadConverter(options.errors)\n  const toHttpErrorResponse = createHttpErrorResponseConverter(options.errors)\n\n  async function clearSession(context: RequestContext): Promise<void> {\n    const { authCookies } = await options.getAuth(context).$context\n    clearStaleSessionCookies(authCookies)\n  }\n\n  async function handleFunctionError(cause: unknown, context: RequestContext): Promise<never> {\n    // oxlint-disable-next-line typescript/only-throw-error -- TanStack uses throwable control-flow objects.\n    if (isNotFound(cause) || isRedirect(cause)) throw cause\n    if (cause instanceof StaleSessionError) {\n      await clearSession(context)\n      // oxlint-disable-next-line typescript/only-throw-error -- Router redirects by throwing this.\n      throw options.signIn()\n    }\n    // oxlint-disable-next-line typescript/only-throw-error -- The client rejects with this and reads its tag.\n    throw toErrorPayload(cause)\n  }\n\n  // A route answers 401 instead of a redirect because fetch would follow it into the HTML shell.\n  async function handleRouteError(cause: unknown, context: RequestContext): Promise<Response> {\n    // oxlint-disable-next-line typescript/only-throw-error -- TanStack uses throwable control-flow objects.\n    if (isNotFound(cause) || isRedirect(cause)) throw cause\n    if (cause instanceof StaleSessionError) await clearSession(context)\n    return toHttpErrorResponse(cause)\n  }\n\n  const functionErrorMiddleware = createMiddleware({ type: 'function' }).server(\n    async ({ next, context }) => {\n      try {\n        return await next()\n      } catch (cause) {\n        return handleFunctionError(cause, context)\n      }\n    },\n  )\n\n  const routeErrorMiddleware = createMiddleware({ type: 'request' }).server(\n    async ({ next, context }) => {\n      try {\n        return await next()\n      } catch (cause) {\n        return handleRouteError(cause, context)\n      }\n    },\n  )\n\n  return { functionErrorMiddleware, routeErrorMiddleware, toErrorPayload, toHttpErrorResponse }\n}\n"],"mappings":"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"}
+{"version":3,"file":"tanstack.js","names":["logger"],"sources":["../src/infrastructure/tanstack/auth.middleware.ts","../src/infrastructure/tanstack/resolve-failure.ts","../src/infrastructure/tanstack/http-error-response.ts","../src/infrastructure/tanstack/session-cookies.ts","../src/infrastructure/tanstack/to-error-payload.ts","../src/infrastructure/tanstack/error.middleware.ts","../src/infrastructure/tanstack/last-login-method.ts"],"sourcesContent":["import { createMiddleware, type Register, type RequestServerOptions } from '@tanstack/react-start'\nimport { getRequestHeaders } from '@tanstack/react-start/server'\nimport { getSessionCookie } from 'better-auth/cookies'\n\nimport { AuthenticationError, StaleSessionError, createLogger } from '@/core'\n\nconst logger = createLogger('auth-middleware')\n\n/** The fields middleware reads; generic callers retain every additional session and user field. */\nexport type AuthSession = {\n  readonly user: { readonly id: string }\n  readonly session: { readonly id: string }\n}\n\n/** Authenticated context retains the application's complete user and session types. */\nexport type RequiredAuthContext<Session extends AuthSession> = {\n  readonly user: Session['user']\n  readonly session: Session['session']\n}\n\n/** Optional authentication supplies both fields together or neither field. */\nexport type AuthContext<Session extends AuthSession> =\n  | RequiredAuthContext<Session>\n  | {\n      readonly user: undefined\n      readonly session: undefined\n    }\n\n/** Select the current request's Better Auth instance from TanStack's registered context. */\nexport type AuthMiddlewareOptions<Session extends AuthSession> = {\n  readonly getAuth: (context: RequestServerOptions<Register, undefined>['context']) => {\n    readonly api: {\n      readonly getSession: (options: { headers: Headers }) => Promise<Session | null>\n    }\n  }\n}\n\n/**\n * Preserve Porte's function and request middleware contracts with application-owned services.\n * Optional lookup failures log once and continue as guests. Required lookup failures propagate.\n */\nexport function createAuthMiddleware<Session extends AuthSession>(\n  options: AuthMiddlewareOptions<Session>,\n) {\n  const extractAuth = createMiddleware({ type: 'function' }).server<AuthContext<Session>>(\n    async ({ next, context }) => {\n      let resolved: Session | null\n      try {\n        resolved = await options.getAuth(context).api.getSession({ headers: getRequestHeaders() })\n      } catch (error) {\n        logger.error('get_session_failed', { error })\n        resolved = null\n      }\n      if (resolved === null)\n        return next<AuthContext<Session>>({ context: { user: undefined, session: undefined } })\n      return next<AuthContext<Session>>({\n        context: { user: resolved.user, session: resolved.session },\n      })\n    },\n  )\n\n  async function resolveRequiredSession(\n    context: RequestServerOptions<Register, undefined>['context'],\n    headers: Headers,\n  ): Promise<Session> {\n    const resolved = await options.getAuth(context).api.getSession({ headers })\n    if (resolved === null) {\n      if (getSessionCookie(headers)) throw new StaleSessionError()\n      throw new AuthenticationError()\n    }\n    return resolved\n  }\n\n  const requireAuth = createMiddleware({ type: 'function' }).server(async ({ next, context }) => {\n    const resolved = await resolveRequiredSession(context, getRequestHeaders())\n    return next<RequiredAuthContext<Session>>({\n      context: { user: resolved.user, session: resolved.session },\n    })\n  })\n  const requireAuthRequest = createMiddleware({ type: 'request' }).server(\n    async ({ request, next, context }) => {\n      const resolved = await resolveRequiredSession(context, request.headers)\n      return next<RequiredAuthContext<Session>>({\n        context: { user: resolved.user, session: resolved.session },\n      })\n    },\n  )\n  return { extractAuth, requireAuth, requireAuthRequest }\n}\n","import { AppError, createLogger, type ErrorTable, type ResolvedError } from '@/core'\nimport type { ErrorPayloadOf } from '@/core'\n\nconst logger = createLogger('error-boundary')\n\n/**\n * Resolve one failure through the table or fall back to the generic replacement, and log it once.\n * Both transport converters call this, so one rule decides the log level: mapped is a warning, unmapped is an error with the cause.\n */\nexport function resolveFailure<Entries>(\n  table: ErrorTable<Entries>,\n  cause: unknown,\n): ResolvedError<ErrorPayloadOf<ErrorTable<Entries>>> {\n  const resolved = table.resolve(cause)\n  if (resolved !== null) {\n    logger.warn('handled_error', {\n      details: { tag: resolved.payload._tag, status: resolved.status },\n    })\n    return resolved\n  }\n  const classification = cause instanceof AppError ? cause.classification : 'unknown'\n  logger.error('unexpected_error', { error: cause, details: { classification } })\n  return table.fallback(cause)\n}\n","import { getReasonPhrase } from 'http-status-codes'\nimport { z } from 'zod'\n\nimport type { ErrorTable, ProblemDetails } from '@/core'\n\nimport { resolveFailure } from './resolve-failure.ts'\n\n// A known delay becomes the header; a null delay sends no header.\nconst RetryAfterSchema = z.object({ retryAfter: z.number() })\n\n/**\n * Build the API route converter for one error table.\n * The body is RFC 9457 problem details; public fields become extension members.\n */\nexport function createHttpErrorResponseConverter<Entries>(table: ErrorTable<Entries>) {\n  return function toHttpErrorResponse(cause: unknown): Response {\n    const { status, payload } = resolveFailure(table, cause)\n    const { _tag, message, ...fields } = payload\n    const body: ProblemDetails = {\n      type: 'about:blank',\n      title: getReasonPhrase(status),\n      detail: message,\n      ...fields,\n    }\n    const headers = new Headers({ 'Content-Type': 'application/problem+json' })\n    const retry = RetryAfterSchema.safeParse(payload)\n    if (retry.success) headers.set('Retry-After', String(retry.data.retryAfter))\n    return Response.json(body, { status, headers })\n  }\n}\n","import { deleteCookie, getRequestHeaders } from '@tanstack/react-start/server'\nimport type { BetterAuthCookies } from 'better-auth'\nimport { parseCookies } from 'better-auth/cookies'\n\ntype AuthCookie = BetterAuthCookies['sessionToken']\ntype DeleteCookieOptions = NonNullable<Parameters<typeof deleteCookie>[1]>\n\n/**\n * Delete the session, session cache, account cache, and remember-me cookies of one instance.\n * Chunks present on the request go too. Names and attributes come from the instance, so custom prefixes and domain cookies clear.\n */\nexport function clearStaleSessionCookies(cookies: BetterAuthCookies): void {\n  const present = [...parseCookies(getRequestHeaders().get('cookie') ?? '').keys()]\n  const definitions = [\n    cookies.sessionToken,\n    cookies.sessionData,\n    cookies.accountData,\n    cookies.dontRememberToken,\n  ]\n  for (const cookie of definitions) {\n    // Better Auth names a chunk `${name}.${index}`, so a missed chunk would resurrect the value.\n    const chunks = present.filter((name) => name.startsWith(`${cookie.name}.`))\n    for (const name of new Set([cookie.name, ...chunks]))\n      deleteCookie(name, deletionOf(cookie.attributes))\n  }\n}\n\nfunction deletionOf(attributes: AuthCookie['attributes']): DeleteCookieOptions {\n  // Better Auth sets `/` and the secure flag at runtime; the types leave both optional.\n  const options: DeleteCookieOptions = {\n    path: attributes.path ?? '/',\n    secure: attributes.secure ?? false,\n  }\n  if (attributes.domain !== undefined) options.domain = attributes.domain\n  return options\n}\n","import { z } from 'zod'\n\nimport { ValidationError, type ErrorPayloadOf, type ErrorTable } from '@/core'\n\nimport { resolveFailure } from './resolve-failure.ts'\n\n// TanStack serializes a validator's issues into `Error.message` as JSON.\nconst SerializedIssuesSchema = z\n  .array(z.object({ message: z.string(), path: z.array(z.union([z.string(), z.number()])) }))\n  .min(1)\n\nfunction reconstructValidationError(cause: unknown): ValidationError | null {\n  if (!(cause instanceof Error)) return null\n  let message: unknown\n  try {\n    message = JSON.parse(cause.message)\n  } catch {\n    return null\n  }\n  const parsed = SerializedIssuesSchema.safeParse(message)\n  return parsed.success ? ValidationError.fromIssues(parsed.data) : null\n}\n\n/**\n * Build the server-function converter for one error table.\n * The result is a plain object, because only own data survives serialization.\n */\nexport function createErrorPayloadConverter<Entries>(table: ErrorTable<Entries>) {\n  return function toErrorPayload(cause: unknown): ErrorPayloadOf<ErrorTable<Entries>> {\n    return resolveFailure(table, reconstructValidationError(cause) ?? cause).payload\n  }\n}\n","import { isNotFound, isRedirect, type AnyRedirect } from '@tanstack/react-router'\nimport { createMiddleware, type Register, type RequestServerOptions } from '@tanstack/react-start'\nimport type { BetterAuthCookies } from 'better-auth'\n\nimport { StaleSessionError, type ErrorTable } from '@/core'\n\nimport { createHttpErrorResponseConverter } from './http-error-response.ts'\nimport { clearStaleSessionCookies } from './session-cookies.ts'\nimport { createErrorPayloadConverter } from './to-error-payload.ts'\n\ntype RequestContext = RequestServerOptions<Register, undefined>['context']\n\n/** The part of a Better Auth instance the boundary reads: its computed cookie definitions. */\nexport type AuthCookieSource = {\n  readonly $context: Promise<{ readonly authCookies: BetterAuthCookies }>\n}\n\n/** The application's error table, its stale-session redirect, and its Better Auth instance. */\nexport type ErrorMiddlewareOptions<Entries> = {\n  readonly errors: ErrorTable<Entries>\n  /** Build the redirect a server function throws for a stale session. */\n  readonly signIn: () => AnyRedirect\n  /** Select the request's Better Auth instance; its cookie definitions say what to clear. */\n  readonly getAuth: (context: RequestContext) => AuthCookieSource\n}\n\n/**\n * Build both transport boundaries from one error table.\n * Register `functionErrorMiddleware` globally. Put `routeErrorMiddleware` first in an API route's `server.middleware`.\n */\nexport function createErrorMiddleware<Entries>(options: ErrorMiddlewareOptions<Entries>) {\n  const toErrorPayload = createErrorPayloadConverter(options.errors)\n  const toHttpErrorResponse = createHttpErrorResponseConverter(options.errors)\n\n  async function clearSession(context: RequestContext): Promise<void> {\n    const { authCookies } = await options.getAuth(context).$context\n    clearStaleSessionCookies(authCookies)\n  }\n\n  async function handleFunctionError(cause: unknown, context: RequestContext): Promise<never> {\n    // oxlint-disable-next-line typescript/only-throw-error -- TanStack uses throwable control-flow objects.\n    if (isNotFound(cause) || isRedirect(cause)) throw cause\n    if (cause instanceof StaleSessionError) {\n      await clearSession(context)\n      // oxlint-disable-next-line typescript/only-throw-error -- Router redirects by throwing this.\n      throw options.signIn()\n    }\n    // oxlint-disable-next-line typescript/only-throw-error -- The client rejects with this and reads its tag.\n    throw toErrorPayload(cause)\n  }\n\n  // A route answers 401 instead of a redirect because fetch would follow it into the HTML shell.\n  async function handleRouteError(cause: unknown, context: RequestContext): Promise<Response> {\n    // oxlint-disable-next-line typescript/only-throw-error -- TanStack uses throwable control-flow objects.\n    if (isNotFound(cause) || isRedirect(cause)) throw cause\n    if (cause instanceof StaleSessionError) await clearSession(context)\n    return toHttpErrorResponse(cause)\n  }\n\n  const functionErrorMiddleware = createMiddleware({ type: 'function' }).server(\n    async ({ next, context }) => {\n      try {\n        return await next()\n      } catch (cause) {\n        return handleFunctionError(cause, context)\n      }\n    },\n  )\n\n  const routeErrorMiddleware = createMiddleware({ type: 'request' }).server(\n    async ({ next, context }) => {\n      try {\n        return await next()\n      } catch (cause) {\n        return handleRouteError(cause, context)\n      }\n    },\n  )\n\n  return { functionErrorMiddleware, routeErrorMiddleware, toErrorPayload, toHttpErrorResponse }\n}\n","import { getRequestHeaders } from '@tanstack/react-start/server'\nimport { parseCookies } from 'better-auth/cookies'\n\n// Better Auth keeps the plugin default private; this is the value LastLoginMethodOptions.cookieName documents.\nconst DEFAULT_COOKIE_NAME = 'better-auth.last_used_login_method'\n\n/**\n * Read the method this browser last signed in with from the current request, for the sign-in loader on the server.\n * Pass `cookieName` only when `integrations.lastLoginMethod.cookieName` is set. Returns `null` when the cookie is absent.\n */\nexport function getLastUsedLoginMethod(cookieName = DEFAULT_COOKIE_NAME): string | null {\n  return parseCookies(getRequestHeaders().get('cookie') ?? '').get(cookieName) ?? null\n}\n"],"mappings":"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"}

package/dist/{unit-of-work-context-ml9L9cyY.d.ts → unit-of-work-context-CPz9rdSS.d.ts}

@@ -1,4 +1,5 @@
-import { o as IEventCollector } from "./index-Bdyh3_xC.js";
+import "./index-BStnggQO.js";
+import { o as IEventCollector } from "./index-DWIRrJMP.js";
 import { BatchItem } from "drizzle-orm/batch";
 //#region src/infrastructure/drizzle-schema.d.ts
 /**
@@ -12,4 +13,4 @@ type DrizzleSchema = Record<string, unknown>;
 declare const eventCollector: IEventCollector;
 //#endregion
 export { DrizzleSchema as n, eventCollector as t };
-//# sourceMappingURL=unit-of-work-context-ml9L9cyY.d.ts.map
+//# sourceMappingURL=unit-of-work-context-CPz9rdSS.d.ts.map

package/dist/unit-of-work-context-CPz9rdSS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-of-work-context-CPz9rdSS.d.ts","names":[],"sources":["../src/infrastructure/drizzle-schema.ts","../src/infrastructure/unit-of-work-context.ts"],"mappings":";;;;;;;;KAKY,gBAAgB;;;;cCuBf,gBAAgB"}

package/dist/{unit-of-work-context-C7vz5OYS.js → unit-of-work-context-DToDpAkv.js}

@@ -1,4 +1,4 @@
-import { t as UnitOfWorkAlreadyActiveError } from "./application-DEerezCl.js";
+import { t as UnitOfWorkAlreadyActiveError } from "./application-DjsQtpgw.js";
 import { panic } from "better-result";
 import { AsyncLocalStorage } from "node:async_hooks";
 
@@ -45,4 +45,4 @@ function currentContext() {
 
 //#endregion
 export { stageD1Statement as i, eventCollector as n, runWithUnitOfWorkContext as r, collectD1Statements as t };
-//# sourceMappingURL=unit-of-work-context-C7vz5OYS.js.map
+//# sourceMappingURL=unit-of-work-context-DToDpAkv.js.map

package/dist/unit-of-work-context-DToDpAkv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-of-work-context-DToDpAkv.js","names":[],"sources":["../src/infrastructure/unit-of-work-context.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks'\n\nimport { panic } from 'better-result'\nimport type { BatchItem } from 'drizzle-orm/batch'\n\nimport { UnitOfWorkAlreadyActiveError, type IEventCollector } from '@/application'\nimport type { DomainEvent } from '@/core'\n\ntype UnitOfWorkContext = { readonly events: DomainEvent[] } & (\n  | { readonly database: 'd1'; readonly statements: BatchItem<'sqlite'>[] }\n  | { readonly database: 'postgres' }\n)\n\n// One async scope isolates events and D1 statements and rejects nesting across both adapters.\nconst storage = new AsyncLocalStorage<UnitOfWorkContext>()\n\n/** Reject nested transactions before database work starts; preserve independent concurrent execution. */\nexport async function runWithUnitOfWorkContext<T>(\n  database: UnitOfWorkContext['database'],\n  work: () => Promise<T>,\n): Promise<T> {\n  if (storage.getStore() !== undefined) throw new UnitOfWorkAlreadyActiveError()\n  const context: UnitOfWorkContext =\n    database === 'd1' ? { database, events: [], statements: [] } : { database, events: [] }\n  return storage.run(context, work)\n}\n\n/** Inject this shared scope into the unit of work and expose its emitter to application handlers. */\nexport const eventCollector: IEventCollector = {\n  emit(event) {\n    currentContext().events.push(event)\n  },\n  collect() {\n    return [...currentContext().events]\n  },\n}\n\n/** Queue one native D1 statement for the active batch; other contexts cannot accept D1 writes. */\nexport function stageD1Statement(statement: BatchItem<'sqlite'>): void {\n  d1Context().statements.push(statement)\n}\n\n/** Read the active D1 batch in staging order for commit. */\nexport function collectD1Statements(): ReadonlyArray<BatchItem<'sqlite'>> {\n  return [...d1Context().statements]\n}\n\nfunction d1Context(): Extract<UnitOfWorkContext, { database: 'd1' }> {\n  const context = currentContext()\n  if (context.database !== 'd1') return panic('D1 statements require a D1 unit of work')\n  return context\n}\n\nfunction currentContext(): UnitOfWorkContext {\n  return storage.getStore() ?? panic('operation requires an active unit of work')\n}\n"],"mappings":";;;;;AAcA,MAAM,UAAU,IAAI,kBAAqC;;AAGzD,eAAsB,yBACpB,UACA,MACY;CACZ,IAAI,QAAQ,SAAS,MAAM,QAAW,MAAM,IAAI,6BAA6B;CAC7E,MAAM,UACJ,aAAa,OAAO;EAAE;EAAU,QAAQ,CAAC;EAAG,YAAY,CAAC;CAAE,IAAI;EAAE;EAAU,QAAQ,CAAC;CAAE;CACxF,OAAO,QAAQ,IAAI,SAAS,IAAI;AAClC;;AAGA,MAAa,iBAAkC;CAC7C,KAAK,OAAO;EACV,eAAe,CAAC,CAAC,OAAO,KAAK,KAAK;CACpC;CACA,UAAU;EACR,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC,MAAM;CACpC;AACF;;AAGA,SAAgB,iBAAiB,WAAsC;CACrE,UAAU,CAAC,CAAC,WAAW,KAAK,SAAS;AACvC;;AAGA,SAAgB,sBAA0D;CACxE,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,UAAU;AACnC;AAEA,SAAS,YAA4D;CACnE,MAAM,UAAU,eAAe;CAC/B,IAAI,QAAQ,aAAa,MAAM,OAAO,MAAM,yCAAyC;CACrF,OAAO;AACT;AAEA,SAAS,iBAAoC;CAC3C,OAAO,QAAQ,SAAS,KAAK,MAAM,2CAA2C;AAChF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {

package/src/application/event-collector.ts

@@ -1,7 +1,7 @@
-import type { Event } from './messages.ts'
+import type { DomainEvent } from '@/core'
 
 /** Records events in the current unit of work; the unit of work collects a snapshot for outbox persistence. */
 export interface IEventCollector {
-  emit(event: Event): void
-  collect(): ReadonlyArray<Event>
+  emit(event: DomainEvent): void
+  collect(): ReadonlyArray<DomainEvent>
 }

package/src/application/handlers.ts

@@ -1,10 +1,10 @@
-import type { Command, Event, Query } from './messages.ts'
+import type { DomainCommand, DomainEvent, DomainQuery } from '@/core'
 
 /**
  * Handles one command with the dependency container and returns the caller's value.
  * A handler that writes inside a transaction opens the unit of work itself. Failures throw.
  */
-export type CommandHandler<TCommand extends Command, Deps, Value> = (
+export type CommandHandler<TCommand extends DomainCommand, Deps, Value> = (
   command: TCommand,
   deps: Deps,
 ) => Promise<Value>
@@ -13,10 +13,13 @@ export type CommandHandler<TCommand extends Command, Deps, Value> = (
  * Handles one query with the read-only view of the container.
  * The view is a type over the same object, so a query cannot name a write capability.
  */
-export type QueryHandler<TQuery extends Query, QueryDeps, Value> = (
+export type QueryHandler<TQuery extends DomainQuery, QueryDeps, Value> = (
   query: TQuery,
   deps: QueryDeps,
 ) => Promise<Value>
 
 /** Completes one subscriber's work for an event. Failures throw. */
-export type EventHandler<TEvent extends Event, Deps> = (event: TEvent, deps: Deps) => Promise<void>
+export type EventHandler<TEvent extends DomainEvent, Deps> = (
+  event: TEvent,
+  deps: Deps,
+) => Promise<void>

package/src/application/index.ts

@@ -1,6 +1,6 @@
 export type { CommandHandler, EventHandler, QueryHandler } from './handlers.ts'
 export type { IMessageStore } from './message-store.ts'
-export type { Command, Event, Message, MessageId, Query } from './messages.ts'
+export type { DomainCommand, DomainEvent, DomainMessage, DomainQuery, MessageId } from '@/core'
 export { MessageBus, type IMessageBus } from './message-bus.ts'
 export type { IOutboxRelay } from './outbox-relay.ts'
 export type {

package/src/application/message-already-processed.error.ts

@@ -1,6 +1,4 @@
-import { AppError, DatabaseError } from '@/core'
-
-import type { MessageId } from './messages.ts'
+import { AppError, DatabaseError, type MessageId } from '@/core'
 
 /** The message's effects already committed. A caller can skip duplicate delivery without repeating those effects. */
 export class MessageAlreadyProcessedError extends AppError {

package/src/application/message-bus.ts

@@ -1,16 +1,22 @@
 import { panic } from 'better-result'
 
-import { createLogger, unreachable } from '@/core'
+import {
+  createLogger,
+  unreachable,
+  type DomainCommand,
+  type DomainEvent,
+  type DomainMessage,
+  type DomainQuery,
+} from '@/core'
 
 import { MessageAlreadyProcessedError } from './message-already-processed.error.ts'
-import type { Command, Event, Message, Query } from './messages.ts'
 import type { Handlers, MessageResult, RegistryMessage } from './registry.ts'
 
 const logger = createLogger('message-bus')
 
 /** The port an entrypoint dispatches through. `AppDeps` names this as `IMessageBus<typeof registry>`. */
 export interface IMessageBus<TRegistry extends Handlers<never>> {
-  handle<TMessage extends Message & RegistryMessage<TRegistry>>(
+  handle<TMessage extends DomainMessage & RegistryMessage<TRegistry>>(
     message: TMessage,
   ): Promise<MessageResult<TMessage, TRegistry>>
 }
@@ -26,7 +32,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
   ) {}
 
   /** Resolves to the handler's own value for a command or query, and to void for an event. */
-  async handle<TMessage extends Message & RegistryMessage<TRegistry>>(
+  async handle<TMessage extends DomainMessage & RegistryMessage<TRegistry>>(
     message: TMessage,
   ): Promise<MessageResult<TMessage, TRegistry>> {
     // SAFETY: the slot for this name is what `MessageResult` names, and dispatch returns its value.
@@ -34,7 +40,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
   }
 
   // oxlint-disable-next-line anti-slop/no-unknown-returns -- one table holds every slot's value; `handle` names it.
-  private dispatch(message: Message): Promise<unknown> {
+  private dispatch(message: DomainMessage): Promise<unknown> {
     if (message.type === 'command') return this.handleCommand(message)
     if (message.type === 'query') return this.handleQuery(message)
     if (message.type === 'event') return this.handleEvent(message)
@@ -43,7 +49,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
   }
 
   // oxlint-disable-next-line anti-slop/no-unknown-returns -- see dispatch.
-  private handleCommand(command: Command): Promise<unknown> {
+  private handleCommand(command: DomainCommand): Promise<unknown> {
     // `satisfies` proved the registry complete, so a missing slot is a broken registry object.
     const handler = this.registry.commands[command.name]
     if (handler === undefined) return panic(`No handler for command ${command.name}`)
@@ -52,7 +58,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
   }
 
   // oxlint-disable-next-line anti-slop/no-unknown-returns -- see dispatch.
-  private handleQuery(query: Query): Promise<unknown> {
+  private handleQuery(query: DomainQuery): Promise<unknown> {
     const handler = this.registry.queries[query.name]
     if (handler === undefined) return panic(`No handler for query ${query.name}`)
     return handler(query, this.deps)
@@ -63,7 +69,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
    * one `AggregateError`. A `MessageAlreadyProcessedError` means that subscriber already committed on
    * an earlier delivery, so it counts as delivered.
    */
-  private async handleEvent(event: Event): Promise<void> {
+  private async handleEvent(event: DomainEvent): Promise<void> {
     const subscriptions = this.registry.events[event.name] ?? []
     const outcomes = await Promise.allSettled(
       subscriptions.map((subscription) => subscription(event, this.deps)),

package/src/application/message-store.ts

@@ -1,4 +1,4 @@
-import type { Event, MessageId } from './messages.ts'
+import type { DomainEvent, MessageId } from '@/core'
 
 /**
  * Stores processed messages and outgoing events in the same transaction as application writes.
@@ -8,5 +8,5 @@ export interface IMessageStore {
   /** Record this message in the transaction; reject an existing record with `MessageAlreadyProcessedError`. */
   claim(messageId: MessageId): Promise<void>
   /** Write the events to the outbox, inside the same boundary as the state change. */
-  persistEvents(events: ReadonlyArray<Event>): Promise<void>
+  persistEvents(events: ReadonlyArray<DomainEvent>): Promise<void>
 }

package/src/application/registry.ts

@@ -1,13 +1,14 @@
+import type { DomainCommand, DomainEvent, DomainMessage, DomainQuery } from '@/core'
+
 import type { CommandHandler, EventHandler, QueryHandler } from './handlers.ts'
-import type { Command, Event, Message, Query } from './messages.ts'
 
 /** One slot per command. `unknown` keeps the slot covariant; `MessageResult` recovers the value. */
-export type CommandRegistry<TCommand extends Command, Deps> = {
+export type CommandRegistry<TCommand extends DomainCommand, Deps> = {
   readonly [M in TCommand as M['name']]: CommandHandler<M, Deps, unknown>
 }
 
 /** One slot per query, typed with the read-only view of the container. */
-export type QueryRegistry<TQuery extends Query, QueryDeps> = {
+export type QueryRegistry<TQuery extends DomainQuery, QueryDeps> = {
   readonly [M in TQuery as M['name']]: QueryHandler<M, QueryDeps, unknown>
 }
 
@@ -15,7 +16,7 @@ export type QueryRegistry<TQuery extends Query, QueryDeps> = {
  * Zero or more subscribers per event. Annotate the object with this type rather than
  * `satisfies`, so an event with no subscribers is still a message the bus accepts.
  */
-export type EventRegistry<TEvent extends Event, Deps> = {
+export type EventRegistry<TEvent extends DomainEvent, Deps> = {
   readonly [M in TEvent as M['name']]?: ReadonlyArray<EventHandler<M, Deps>>
 }
 
@@ -24,16 +25,16 @@ export type EventRegistry<TEvent extends Event, Deps> = {
  * makes a missing handler a compile error. `Deps extends QueryDeps` is checked here, the one
  * place both types meet: the read view must be a subset of the container.
  */
-export type MessageRegistry<TMessage extends Message, Deps extends QueryDeps, QueryDeps> = {
-  readonly commands: CommandRegistry<Extract<TMessage, Command>, Deps>
-  readonly queries: QueryRegistry<Extract<TMessage, Query>, QueryDeps>
-  readonly events: EventRegistry<Extract<TMessage, Event>, Deps>
+export type MessageRegistry<TMessage extends DomainMessage, Deps extends QueryDeps, QueryDeps> = {
+  readonly commands: CommandRegistry<Extract<TMessage, DomainCommand>, Deps>
+  readonly queries: QueryRegistry<Extract<TMessage, DomainQuery>, QueryDeps>
+  readonly events: EventRegistry<Extract<TMessage, DomainEvent>, Deps>
 }
 
 // Method syntax makes the parameters bivariant, so an app's slot, typed for one message, fits.
 // oxlint-disable-next-line anti-slop/no-unknown-returns -- one table holds every slot's value; `MessageResult` names it.
-type Slot<Deps> = { handle(message: Message, deps: Deps): Promise<unknown> }['handle']
-type Subscription<Deps> = { handle(event: Event, deps: Deps): Promise<void> }['handle']
+type Slot<Deps> = { handle(message: DomainMessage, deps: Deps): Promise<unknown> }['handle']
+type Subscription<Deps> = { handle(event: DomainEvent, deps: Deps): Promise<void> }['handle']
 
 /**
  * The registry as the bus routes it: each table keyed by name. The app's names are unknown
@@ -64,10 +65,10 @@ type SlotValue<TSlots, TName extends string> = TName extends keyof TSlots
 
 /** The value `bus.handle(message)` resolves to: the slot's own return type, or void for an event. */
 export type MessageResult<
-  TMessage extends Message,
+  TMessage extends DomainMessage,
   TRegistry extends Handlers<never>,
-> = TMessage extends Command
+> = TMessage extends DomainCommand
   ? SlotValue<TRegistry['commands'], TMessage['name']>
-  : TMessage extends Query
+  : TMessage extends DomainQuery
     ? SlotValue<TRegistry['queries'], TMessage['name']>
     : void

package/src/application/unit-of-work.ts

@@ -1,7 +1,8 @@
+import type { MessageId } from '@/core'
+
 import type { IEventCollector } from './event-collector.ts'
 import { MessageAlreadyProcessedError } from './message-already-processed.error.ts'
 import type { IMessageStore } from './message-store.ts'
-import type { MessageId } from './messages.ts'
 import type { IOutboxRelay } from './outbox-relay.ts'
 import type { ITransaction } from './transaction.ts'
 

package/src/core/define-messages.ts

@@ -0,0 +1,136 @@
+import { v7 as uuidv7 } from 'uuid'
+import { z } from 'zod'
+
+import type { DomainCommand, DomainEvent, DomainQuery, MessageId } from './messages.ts'
+
+/** Payload schemas keyed by message name. A payload never carries `type`, `name`, or `id`. */
+export type PayloadSchemas = Readonly<Record<string, z.ZodType<object>>>
+
+/** An application's messages: one list of payload schemas per kind. */
+export type MessageDefinition = {
+  readonly commands: PayloadSchemas
+  readonly events: PayloadSchemas
+  readonly queries: PayloadSchemas
+}
+
+type AnyMessages = { readonly definition: MessageDefinition }
+type Def<Messages extends AnyMessages> = Messages['definition']
+type Payload<Schemas extends PayloadSchemas, Name extends keyof Schemas> = z.output<Schemas[Name]>
+
+/** Every command of an application: `CommandOf<typeof messages>`. */
+export type CommandOf<Messages extends AnyMessages> = {
+  [Name in keyof Def<Messages>['commands'] & string]: DomainCommand<Name> &
+    Payload<Def<Messages>['commands'], Name>
+}[keyof Def<Messages>['commands'] & string]
+
+/** Every event of an application: `EventOf<typeof messages>`. */
+export type EventOf<Messages extends AnyMessages> = {
+  [Name in keyof Def<Messages>['events'] & string]: DomainEvent<Name> &
+    Payload<Def<Messages>['events'], Name>
+}[keyof Def<Messages>['events'] & string]
+
+/** Every query of an application: `QueryOf<typeof messages>`. */
+export type QueryOf<Messages extends AnyMessages> = {
+  [Name in keyof Def<Messages>['queries'] & string]: DomainQuery<Name> &
+    Payload<Def<Messages>['queries'], Name>
+}[keyof Def<Messages>['queries'] & string]
+
+/** Every message of an application: what the registry and the bus are typed with. */
+export type MessageOf<Messages extends AnyMessages> =
+  | CommandOf<Messages>
+  | EventOf<Messages>
+  | QueryOf<Messages>
+
+/**
+ * What `defineMessages` returns. The factories build messages for in-process dispatch without
+ * parsing; the data is already typed. The schemas parse untrusted input at a boundary.
+ */
+export type AppMessages<Definition extends MessageDefinition> = {
+  readonly definition: Definition
+  /** Build a command. `id` defaults to a uuid v7; a webhook passes the provider's key, `stripe:event:evt_123`. */
+  createCommand<Name extends keyof Definition['commands'] & string>(
+    name: Name,
+    payload: Payload<Definition['commands'], Name>,
+    id?: MessageId,
+  ): DomainCommand<Name> & Payload<Definition['commands'], Name>
+  /** Build an event. `id` defaults to a uuid v7, which also orders it in time. */
+  createEvent<Name extends keyof Definition['events'] & string>(
+    name: Name,
+    payload: Payload<Definition['events'], Name>,
+    id?: MessageId,
+  ): DomainEvent<Name> & Payload<Definition['events'], Name>
+  /** Build a query. No id: nothing claims a read. */
+  createQuery<Name extends keyof Definition['queries'] & string>(
+    name: Name,
+    payload: Payload<Definition['queries'], Name>,
+  ): DomainQuery<Name> & Payload<Definition['queries'], Name>
+  readonly commandSchema: z.ZodType<CommandOf<AppMessages<Definition>>>
+  readonly eventSchema: z.ZodType<EventOf<AppMessages<Definition>>>
+  readonly querySchema: z.ZodType<QueryOf<AppMessages<Definition>>>
+  /** What a queue body may be: a command or an event. Queries never cross a queue. */
+  readonly queueSchema: z.ZodType<
+    CommandOf<AppMessages<Definition>> | EventOf<AppMessages<Definition>>
+  >
+}
+
+type RoutingField = 'type' | 'name' | 'id'
+
+/** A payload that declares a routing field maps to `never`, so `defineMessages` rejects it. */
+type WithoutRoutingFields<Schemas extends PayloadSchemas> = {
+  readonly [Name in keyof Schemas]: keyof z.output<Schemas[Name]> & RoutingField extends never
+    ? Schemas[Name]
+    : never
+}
+
+/** The compile-time rule: no payload of any kind declares `type`, `name`, or `id`. */
+type ValidDefinition<Definition extends MessageDefinition> = {
+  readonly commands: WithoutRoutingFields<Definition['commands']>
+  readonly events: WithoutRoutingFields<Definition['events']>
+  readonly queries: WithoutRoutingFields<Definition['queries']>
+}
+
+const MessageIdSchema = z.string().min(1)
+
+/** One full message schema: the routing fields joined to the payload. */
+function messageSchema(
+  type: 'command' | 'event' | 'query',
+  name: string,
+  payload: z.ZodType<object>,
+) {
+  const routing =
+    type === 'query'
+      ? z.object({ type: z.literal(type), name: z.literal(name) })
+      : z.object({ type: z.literal(type), name: z.literal(name), id: MessageIdSchema })
+  return routing.and(payload)
+}
+
+/** A union over every message of one kind. Empty when the application has none of that kind. */
+function unionOf(type: 'command' | 'event' | 'query', schemas: PayloadSchemas) {
+  return z.union(
+    Object.entries(schemas).map(([name, payload]) => messageSchema(type, name, payload)),
+  )
+}
+
+/**
+ * Define an application's messages once. The key is the name; the factories add the routing
+ * fields `type`, `name`, and `id`. A payload that declares one of them is a compile error.
+ */
+export function defineMessages<const Definition extends MessageDefinition>(
+  definition: Definition & ValidDefinition<Definition>,
+): AppMessages<Definition> {
+  const commandSchema = unionOf('command', definition.commands)
+  const eventSchema = unionOf('event', definition.events)
+  const querySchema = unionOf('query', definition.queries)
+  return {
+    definition,
+    createCommand: (name, payload, id = uuidv7()) => ({ ...payload, type: 'command', name, id }),
+    createEvent: (name, payload, id = uuidv7()) => ({ ...payload, type: 'event', name, id }),
+    createQuery: (name, payload) => ({ ...payload, type: 'query', name }),
+    commandSchema: commandSchema.pipe(z.custom<CommandOf<AppMessages<Definition>>>()),
+    eventSchema: eventSchema.pipe(z.custom<EventOf<AppMessages<Definition>>>()),
+    querySchema: querySchema.pipe(z.custom<QueryOf<AppMessages<Definition>>>()),
+    queueSchema: z
+      .union([commandSchema, eventSchema])
+      .pipe(z.custom<CommandOf<AppMessages<Definition>> | EventOf<AppMessages<Definition>>>()),
+  }
+}

package/src/core/entity.ts

@@ -0,0 +1,33 @@
+import type { DomainEvent } from './messages.ts'
+
+/** What an aggregate's plain data must have: an identity. A branded id keeps its brand. */
+export type EntityData = { readonly id: string }
+
+/**
+ * The base of an aggregate: its identity, the events it raised, and the plain data a repository
+ * stores. The subclass keeps its constructor private and declares `static restore(data: Data)`,
+ * the one door a repository rebuilds it through. A repository drains the events after `save`.
+ */
+export abstract class Entity<Data extends EntityData, TEvent extends DomainEvent = DomainEvent> {
+  private events: TEvent[] = []
+
+  abstract readonly id: Data['id']
+
+  /** Record one event with the state change that caused it. The unit of work commits both. */
+  protected addEvent(event: TEvent): void {
+    this.events.push(event)
+  }
+
+  /** A copy of the events raised since the last `clearEvents`. */
+  collectEvents(): ReadonlyArray<TEvent> {
+    return [...this.events]
+  }
+
+  /** Forget the raised events once the boundary has taken them. */
+  clearEvents(): void {
+    this.events = []
+  }
+
+  /** Plain data for the repository. The subclass's `restore(data)` accepts exactly this. */
+  abstract toPlainObject(): Data
+}

package/src/core/identity.ts

@@ -0,0 +1,29 @@
+import { v7 as uuidv7 } from 'uuid'
+import { z } from 'zod'
+
+/** A string only `create()` or `schema.parse()` of the same kind can produce. */
+export type Id<Brand extends string> = string & z.core.$brand<Brand>
+
+/** One id kind the application mints. `schema` parses untrusted input; `create` mints a uuid v7. */
+export type IdDefinition<Brand extends string> = {
+  readonly schema: z.core.$ZodBranded<z.ZodUUID, Brand>
+  /** Mint a new time-ordered id. No parse: we produced it, so it is valid by construction. */
+  create(): Id<Brand>
+}
+
+/** The id type of a definition: `type CallId = IdOf<typeof CallId>`. */
+export type IdOf<Definition extends IdDefinition<string>> = z.output<Definition['schema']>
+
+/**
+ * Define an id kind the application mints: `export const CallId = defineId('CallId')`.
+ * An id another system mints, such as a provider's call id, stays a plain branded schema.
+ */
+export function defineId<const Brand extends string>(brand: Brand): IdDefinition<Brand> {
+  const schema = z.uuidv7({ error: `Invalid ${brand}` })
+  return {
+    // SAFETY: `brand()` is type-only and returns a conditional TypeScript cannot reduce for a generic brand; for every literal it is this branded schema.
+    schema: schema.brand<Brand>() as z.core.$ZodBranded<z.ZodUUID, Brand>,
+    // SAFETY: uuidv7() always yields a valid v7 uuid, and the brand is a compile-time mark only.
+    create: () => uuidv7() as Id<Brand>,
+  }
+}

package/src/core/index.ts

@@ -32,6 +32,25 @@ export {
 } from './problem-details.ts'
 export { DatabaseError, type DatabaseFailure, type D1ConstraintKind } from './database.error.ts'
 export { notImplemented, unreachable } from './defects.ts'
+export { defineId, type Id, type IdDefinition, type IdOf } from './identity.ts'
+export {
+  defineMessages,
+  type AppMessages,
+  type CommandOf,
+  type EventOf,
+  type MessageDefinition,
+  type MessageOf,
+  type PayloadSchemas,
+  type QueryOf,
+} from './define-messages.ts'
+export type {
+  DomainCommand,
+  DomainEvent,
+  DomainMessage,
+  DomainQuery,
+  MessageId,
+} from './messages.ts'
+export { Entity, type EntityData } from './entity.ts'
 export {
   shouldRetryFailure,
   type FailureClassification,