lambder 9.0.2 → 10.0.1

package/dist/core/LambderResponseBuilder.js

@@ -1,5 +1,5 @@
 import { LambderResponse } from "./LambderResponse.js";
-import { buildApiEnvelope } from "../api/LambderApiEnvelope.js";
+import { plainRefusalEnvelope } from "../api/LambderApiEnvelope.js";
 /**
  * Builds the responses of routes, hooks and error handlers. An API handler
  * never holds one: it returns its output or refuses, and writes headers and
@@ -92,7 +92,7 @@ export default class LambderResponseBuilder {
     }
     ;
     versionExpired(options) {
-        return this.api(null, { versionExpired: true }, options);
+        return this.apiRefusal({ versionExpired: true }, options);
     }
     ;
     fileBase64(fileBase64, mimeType, options) {
@@ -135,16 +135,17 @@ export default class LambderResponseBuilder {
     }
     ;
     /**
-     * An API envelope written by hand: what a hook, an input validation
-     * handler or a global error handler answers an API call with (a refusal
-     * flag, an errorMessage, a crash). The payload goes out as given; an API
-     * handler's own output is parsed through its schema by the instance
-     * instead. The logList channel is what the request accumulated unless the
-     * config names its own.
+     * An API call answered from outside its handler: what a hook, a fallback,
+     * the input validation handler or the global error handler answers with.
+     * It is always a refusal (a refusal message, or one of the versionExpired,
+     * sessionExpired and notAuthorized flags) with a null payload, so a
+     * caller's success is only ever the handler's parsed output. Its message
+     * carries a framework code or none, and no data, since it answers outside
+     * any one endpoint's declared refusals. The logList channel is what the
+     * request accumulated unless the config names its own.
      */
-    api(payload, config = {}, options) {
-        const envelope = buildApiEnvelope(this.apiVersion, payload, { ...config, logList: config.logList || this.ctx?.logList });
-        return this.json(envelope, options);
+    apiRefusal(config, options) {
+        return this.json(plainRefusalEnvelope(this.apiVersion, config, "res.apiRefusal()", this.ctx?.logList), options);
     }
     ;
 }

package/dist/index.d.ts

@@ -38,18 +38,20 @@ export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_L
 export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignatureMap.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
-export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
-export type { LambderApiEnvelopeConfig, LambderValidationAnswerBody } from "./api/LambderApiEnvelope.js";
+export { successEnvelope, refusalEnvelope, plainRefusalEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
+export type { LambderValidationAnswerBody } from "./api/LambderApiEnvelope.js";
 export { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./api/LambderApiValidationRefusal.js";
 export { LambderApiOutputValidationError } from "./api/LambderApiOutputValidationError.js";
+export { checkedRefusal } from "./api/LambderApiRefusals.js";
 export { LambderInvokeError, isLambderInvokeError } from "./invoke/LambderInvokeOutcome.js";
 export type { LambderInvokeOutcome, LambderInvokeFailure, LambderInvokeValidationFailure, LambderInvokeCrashFailure, LambderInvokePayloadTooLargeFailure, LambderInvokeEnvelopeFailure, LambderInvokeDeliveryFailure, LambderInvokeFailureReason, LambderInvokeFunctionError, } from "./invoke/LambderInvokeOutcome.js";
 export { default as LambderInvokeCaller, LAMBDER_INVOKE_MAX_EVENT_BYTES, } from "./invoke/LambderInvokeCaller.js";
 export type { LambderInvokeCallerOptions, LambderInvokeCallOptions, LambderInvokeFailureHandler, LambderInvokeLogListHandler, LambderInvokeTransport, LambderInvokeTransportResult, LambderInvokeRequestInit, LambderInvokeEventInit, } from "./invoke/LambderInvokeCaller.js";
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 export type { LambderCrashDetail, LambderCrashCause } from "./shared/wire/LambderCrashDetail.js";
-export { LambderApiRefusal, isLambderApiRefusal, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
-export type { LambderApiRefusalOptions, LambderRefusalMessage, LambderAppRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/wire/LambderApiRefusal.js";
+export { LambderApiRefusal, isLambderApiRefusal, isLambderRefusalCode, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+export type { LambderApiRefusalOptions, LambderRefusalMessage, LambderPlainRefusalMessage, LambderUncheckedRefusalMessage, LambderRefusalCode, LambderRefuseOptions, LambderDeclaredRefuseOptions, LambderDeclaredRefuse, } from "./shared/wire/LambderApiRefusal.js";
+export { isObjectPayload } from "./shared/wire/LambderObjectPayload.js";
 export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
 export { default as LambderResolver } from "./core/LambderResolver.js";
 export { default as LambderSessionManager } from "./session/LambderSessionManager.js";
@@ -64,7 +66,7 @@ export type { LambderSessionCrypto } from "./session/LambderSessionCrypto.js";
 export { LambderDdbSessionStore } from "./stores/LambderDdbSessionStore.js";
 export type { LambderDdbSessionStoreOptions } from "./stores/LambderDdbSessionStore.js";
 export { LambderResponse, finalizeResponse, answerFromResponse, responseFromAnswer, type LambderHttpResponse, type LambderHeadersInput, type LambderFinalizeOptions, type LambderResponseCompressionSettings, type LambderResponseCompressionOption, } from "./core/LambderResponse.js";
-export type { LambderHttpStatusCode } from "./shared/wire/LambderHttpStatus.js";
+export type { LambderHttpStatusCode, LambderRefusalStatusCode } from "./shared/wire/LambderHttpStatus.js";
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
 export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
@@ -88,7 +90,7 @@ export type { LambderS3UploadBucketOptions } from "./stores/LambderS3UploadBucke
 export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js";
 export type { LambderMemoryUploadBucketOptions, LambderMemoryUploadObject } from "./stores/LambderMemoryUploadBucket.js";
 export { checkUploadRule } from "./shared/contracts/LambderUploadBucket.js";
-export type { LambderUploadBucket, LambderUploadRule, LambderUploadFileFacts, LambderUploadTicket, LambderUploadVerdict, LambderUploadRuleVerdict, LambderUploadObjectOptions, LambderUploadContentDisposition, } from "./shared/contracts/LambderUploadBucket.js";
+export type { LambderUploadBucket, LambderUploadRule, LambderUploadFileFacts, LambderUploadTicket, LambderUploadMethod, LambderUploadVerdict, LambderUploadRuleVerdict, LambderUploadObjectOptions, LambderUploadContentDisposition, } from "./shared/contracts/LambderUploadBucket.js";
 export { LambderUploadFileFactsSchema, LambderUploadTicketSchema } from "./shared/wire/LambderUploadSchemas.js";
 export { refuseUnacceptedUpload } from "./shared/wire/LambderUploadRefusal.js";
 export { LambderUploadRunner, LambderUploadError } from "./client/LambderUploadRunner.js";
@@ -123,17 +125,19 @@ export type { LambderDdbIdempotencyStoreOptions } from "./stores/LambderDdbIdemp
 export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
 export { lambderGuard, lambderRateLimitKey } from "./core/LambderPolicyBuilders.js";
 export { lambderGuardBuilder } from "./api/LambderApiGuards.js";
-export type { LambderGuardBuilder, LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderGuardRunAt, LambderAllowedGuardNames, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf, } from "./api/LambderApiGuards.js";
+export type { LambderGuardBuilder, LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderGuardRunAt, LambderAllowedGuardNames, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf, LambderGuardRefusals, LambderGuardRefusalNamesOf, } from "./api/LambderApiGuards.js";
+export { LambderApiRefusalValidationError } from "./api/LambderApiRefusals.js";
+export type { LambderRefusalDeclaration, LambderRefusalVocabulary, LambderApiAllowedRefusal, LambderApiAllowedRefusals, LambderEndpointRefusals, LambderRefusalsOption, LambderRefusalNamesIn, LambderHandlerRefusalsOf, LambderWireRefusalsOf, } from "./api/LambderApiRefusals.js";
 export { lambderRateLimitKeyBuilder, rateLimitRefusal, DEFAULT_RATE_LIMIT_REFUSAL } from "./api/LambderApiRateLimits.js";
 export type { LambderRateLimitKeyBuilder } from "./api/LambderApiRateLimits.js";
 export type { LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult, LambderChargeablePolicyNames, LambderChargeKeyArgs, LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderRateLimitChargeAt, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderRateLimitOption, } from "./api/LambderApiRateLimits.js";
 export type { LambderApiIdempotencyConfig } from "./api/LambderApiIdempotency.js";
-export type { LambderGuardsOptionValue, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
+export type { LambderGuardsOptionValue, LambderRateLimitMessage, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderRefusalsOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
 export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
 export type { LambderApiOptionEntries, LambderApiOptionEntry, LambderRateLimitPolicyEntry, LambderGuardDeclarationEntry, LambderApisWithGuard, LambderApisGuardedBy, LambderApisWithMode, LambderGuardParamOf, } from "./shared/wire/LambderApiOptionEntries.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
-export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiSuccessEnvelope, LambderApiRefusalEnvelope, LambderRefusalEnvelopeFields, LambderApiRefusalConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderContractRefusalsOf, LambderContractRefusalMessage, LambderContractRefusals, LambderContractAnyRefusalMessage, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent, LambderHttpEventFormat } from "./core/LambderContext.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";

package/dist/index.js

@@ -27,16 +27,18 @@ export { apiSignatureOf } from "./api/LambderApiSignature.js";
 export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignatureMap.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
-export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
+export { successEnvelope, refusalEnvelope, plainRefusalEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
 export { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./api/LambderApiValidationRefusal.js";
 export { LambderApiOutputValidationError } from "./api/LambderApiOutputValidationError.js";
+export { checkedRefusal } from "./api/LambderApiRefusals.js";
 // Calling a Lambder app from another lambda (server-only: the Lambda SDK, zlib)
 export { LambderInvokeError, isLambderInvokeError } from "./invoke/LambderInvokeOutcome.js";
 export { default as LambderInvokeCaller, LAMBDER_INVOKE_MAX_EVENT_BYTES, } from "./invoke/LambderInvokeCaller.js";
 // A crash described for a caller allowed to see it (the envelope's `crash` field)
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere)
-export { LambderApiRefusal, isLambderApiRefusal, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+export { LambderApiRefusal, isLambderApiRefusal, isLambderRefusalCode, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+export { isObjectPayload } from "./shared/wire/LambderObjectPayload.js";
 export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
 export { default as LambderResolver } from "./core/LambderResolver.js";
 export { default as LambderSessionManager } from "./session/LambderSessionManager.js";
@@ -86,6 +88,8 @@ export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotency
 // Declarative per-API policies: guards
 export { lambderGuard, lambderRateLimitKey } from "./core/LambderPolicyBuilders.js";
 export { lambderGuardBuilder } from "./api/LambderApiGuards.js";
+// Declarative per-API policies: declared refusals
+export { LambderApiRefusalValidationError } from "./api/LambderApiRefusals.js";
 // Declarative per-API policies: rate limits
 export { lambderRateLimitKeyBuilder, rateLimitRefusal, DEFAULT_RATE_LIMIT_REFUSAL } from "./api/LambderApiRateLimits.js";
 // The declared options as plain data: what apiOptionEntries() reports and

package/dist/invoke/LambderInvokeCaller.d.ts

@@ -24,7 +24,7 @@ import type { APIGatewayProxyEventV2, Context } from "aws-lambda";
 import { type LambderInvokeFailure, type LambderInvokeOutcome } from "./LambderInvokeOutcome.js";
 import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
 import type { LambdaClient, LambdaClientConfig } from "@aws-sdk/client-lambda";
-import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiContractShape, LambderContractRefusalMessage } from "../shared/wire/LambderApiContract.js";
 import { type LambderCallArgs, type LambderContractOutputOf, type LambderGuardInputsProviderOption, type LambderSharedCallOptions } from "../shared/wire/LambderCallOptions.js";
 import { type LambderCompressionOption } from "../shared/wire/LambderCompressionOption.js";
 import { type LambderInvokeSession, type LambderLambdaHttpResult } from "./LambderLambdaEvent.js";
@@ -214,14 +214,13 @@ export default class LambderInvokeCaller<TContract extends LambderApiContractSha
      * comes from the contract rather than a type parameter, so a call site
      * cannot replace it by annotating what it assigns to.
      */
-    apiOutcome<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderInvokeCallOptions>): Promise<LambderInvokeOutcome<LambderContractOutputOf<TContract, TApiName>>>;
+    apiOutcome<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderInvokeCallOptions>): Promise<LambderInvokeOutcome<LambderContractOutputOf<TContract, TApiName>, LambderContractRefusalMessage<TContract, TApiName>>>;
     /**
      * The declared output, or a thrown LambderInvokeError carrying the
      * outcome. A failed dependency is a failed request: the throw reaches the
-     * app's global error handler with the callee's error as its cause. The
-     * resolver lets a handler answer null only when the output allows it or
-     * beside a reason (LambderApiAnswer), so null arrives only for a
-     * nullable output.
+     * app's global error handler with the callee's error as its cause. Only
+     * the callee handler's own output reads as a success, so what this
+     * returns is always the contract's output.
      */
     api<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderInvokeCallOptions>): Promise<LambderContractOutputOf<TContract, TApiName>>;
     /**

package/dist/invoke/LambderInvokeCaller.js

@@ -227,7 +227,7 @@ export default class LambderInvokeCaller {
             apiName,
             functionName: this.functionName,
             status: init.status,
-            errorMessage: init.errorMessage,
+            refusal: init.refusal,
             crash: init.crash,
             functionError: init.functionError,
             logList,
@@ -246,7 +246,7 @@ export default class LambderInvokeCaller {
             logList,
             cookies: init.cookies ?? [],
             ...(init.status !== undefined ? { status: init.status } : {}),
-            ...(init.errorMessage !== undefined ? { errorMessage: init.errorMessage } : {}),
+            ...(init.refusal !== undefined ? { refusal: init.refusal } : {}),
             ...(init.retryAfterSeconds !== undefined ? { retryAfterSeconds: init.retryAfterSeconds } : {}),
             ...(init.zodError !== undefined ? { zodError: init.zodError } : {}),
             ...(init.crash !== undefined ? { crash: init.crash } : {}),
@@ -288,6 +288,9 @@ export default class LambderInvokeCaller {
      */
     async dispatch(apiName, payload, options = {}) {
         const idempotentAttempt = beginIdempotentAttempt(options.idempotencyKey);
+        // The reader cannot check a refusal's code against declarations it
+        // does not have; the callee never sends one its endpoint did not
+        // declare, which is what the endpoint's message type stands for.
         const outcome = await this.dispatchAttempt(apiName, payload, options, idempotentAttempt);
         // Only the first settle counts: an attempt that never left settled
         // itself as not sent.
@@ -378,11 +381,10 @@ export default class LambderInvokeCaller {
         // The answer's Set-Cookie values, so a session the callee rotated or
         // cleared is visible to whoever is carrying it.
         const cookies = http.cookies;
-        // The declared output, by the callee's own typing: a handler returns
-        // its output, so a success payload is null only where the output
-        // allows null.
+        // The callee handler's output: only a handler's answer reads as a
+        // success, and an output is always an object or an array.
         if (outcome.ok)
-            return { ok: true, payload: (outcome.payload ?? null), response: outcome.response, logList, cookies };
+            return { ok: true, payload: outcome.payload, response: outcome.response, logList, cookies };
         const shared = { status: outcome.status, retryAfterSeconds: outcome.retryAfterSeconds, logList, cookies };
         // Each failure reason carries different evidence, and the outcome
         // union says which: a rejected input has its issues and no envelope,
@@ -399,7 +401,7 @@ export default class LambderInvokeCaller {
             return await this.failureOutcome(apiName, {
                 ...shared,
                 reason: 'server',
-                errorMessage: outcome.errorMessage,
+                refusal: outcome.refusal,
                 response: outcome.response,
                 crash: outcome.response?.crash,
                 cause: outcome.error,
@@ -408,7 +410,7 @@ export default class LambderInvokeCaller {
         }
         return await this.failureOutcome(apiName, {
             ...shared,
-            ...(outcome.reason === 'errorMessage' ? { reason: outcome.reason, errorMessage: outcome.errorMessage } : { reason: outcome.reason }),
+            ...(outcome.reason === 'refusal' ? { reason: outcome.reason, refusal: outcome.refusal } : { reason: outcome.reason }),
             response: outcome.response,
             crash: outcome.response.crash,
         });
@@ -429,10 +431,9 @@ export default class LambderInvokeCaller {
     /**
      * The declared output, or a thrown LambderInvokeError carrying the
      * outcome. A failed dependency is a failed request: the throw reaches the
-     * app's global error handler with the callee's error as its cause. The
-     * resolver lets a handler answer null only when the output allows it or
-     * beside a reason (LambderApiAnswer), so null arrives only for a
-     * nullable output.
+     * app's global error handler with the callee's error as its cause. Only
+     * the callee handler's own output reads as a success, so what this
+     * returns is always the contract's output.
      */
     async api(apiName, ...rest) {
         const [payload, options] = rest;

package/dist/invoke/LambderInvokeOutcome.d.ts

@@ -10,10 +10,10 @@
  * should not have to read the whole class to find it. None of these functions
  * touch the caller's state.
  */
-import type { LambderApiEnvelopeBody } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiRefusalEnvelope, LambderApiSuccessEnvelope } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiFailureReason, LambderValidationError } from "../shared/wire/LambderApiOutcome.js";
 import type { LambderCrashDetail } from "../shared/wire/LambderCrashDetail.js";
-import type { LambderAppRefusalMessage } from "../shared/wire/LambderApiRefusal.js";
+import type { LambderUncheckedRefusalMessage } from "../shared/wire/LambderApiRefusal.js";
 export type LambderInvokeFailureReason = LambderApiFailureReason | 'crash' | 'protocol' | 'payloadTooLarge';
 /** Lambda's own error payload for a FunctionError invocation. */
 export type LambderInvokeFunctionError = {
@@ -21,13 +21,17 @@ export type LambderInvokeFunctionError = {
     errorMessage?: string;
     trace?: string[];
 };
-/** What every invoke failure carries, whatever went wrong. */
-type LambderInvokeFailureFields = {
+/**
+ * What every invoke failure carries, whatever went wrong. TMessage is the
+ * refusal message the endpoint can answer with (LambderContractRefusalMessage),
+ * on every arm, as on the browser caller's outcome.
+ */
+type LambderInvokeFailureFields<TMessage extends LambderUncheckedRefusalMessage> = {
     ok: false;
     /** HTTP status, when the callee answered. */
     status?: number;
-    /** Envelope errorMessage, when the callee provided one: always the message object, a plain string having been read as one (refusalMessageOf). */
-    errorMessage?: LambderAppRefusalMessage;
+    /** The envelope's refusal, when the callee provided one: always the message object, a plain string having been read as one (refusalMessageOf). */
+    refusal?: TMessage;
     /** Seconds to wait before retrying, from the answer's Retry-After header. */
     retryAfterSeconds?: number;
     /** Always present: the error api() throws for this failure, with the callee's error as its cause when one is known. */
@@ -38,31 +42,31 @@ type LambderInvokeFailureFields = {
     cookies: string[];
 };
 /** HTTP 422: the callee rejected the input against the API's schema. Always carries the issues. */
-export type LambderInvokeValidationFailure = LambderInvokeFailureFields & {
+export type LambderInvokeValidationFailure<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderInvokeFailureFields<TMessage> & {
     reason: 'validation';
     zodError: LambderValidationError;
 };
 /** Lambda reported a FunctionError: the callee failed outside the framework (an init failure, a timeout, out of memory). Always carries the runtime's error payload. */
-export type LambderInvokeCrashFailure = LambderInvokeFailureFields & {
+export type LambderInvokeCrashFailure<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderInvokeFailureFields<TMessage> & {
     reason: 'crash';
     functionError: LambderInvokeFunctionError;
 };
 /** Refused before sending: the serialized event is over the invoke cap. Always carries its size. */
-export type LambderInvokePayloadTooLargeFailure = LambderInvokeFailureFields & {
+export type LambderInvokePayloadTooLargeFailure<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderInvokeFailureFields<TMessage> & {
     reason: 'payloadTooLarge';
     /** The event's byte size, so a caller can say by how much it is over. */
     bytes: number;
 };
-/** The callee answered, and the envelope itself says the call is refused. Always carries that envelope, and an `errorMessage` refusal always carries its message. */
-export type LambderInvokeEnvelopeFailure = LambderInvokeFailureFields & {
-    response: LambderApiEnvelopeBody<any>;
+/** The callee answered, and the envelope itself says the call is refused. Always carries that envelope, and a `refusal` failure always carries the refusal. */
+export type LambderInvokeEnvelopeFailure<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderInvokeFailureFields<TMessage> & {
+    response: LambderApiRefusalEnvelope;
     /** The callee's crash detail, when its global error handler sent one (the envelope's `crash` field). */
     crash?: LambderCrashDetail;
 } & ({
     reason: 'versionExpired' | 'sessionExpired' | 'notAuthorized';
 } | {
-    reason: 'errorMessage';
-    errorMessage: LambderAppRefusalMessage;
+    reason: 'refusal';
+    refusal: TMessage;
 });
 /**
  * Nothing usable came back: the invoke never arrived or was given up on, the
@@ -71,9 +75,9 @@ export type LambderInvokeEnvelopeFailure = LambderInvokeFailureFields & {
  * answered with Lambder's own envelope, which is how a crash detail and a
  * logList arrive with it.
  */
-export type LambderInvokeDeliveryFailure = LambderInvokeFailureFields & {
+export type LambderInvokeDeliveryFailure<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderInvokeFailureFields<TMessage> & {
     reason: 'network' | 'timeout' | 'server' | 'protocol' | 'unknown';
-    response?: LambderApiEnvelopeBody<any>;
+    response?: LambderApiRefusalEnvelope;
     /** The callee's crash detail, when its global error handler sent one (the envelope's `crash` field). */
     crash?: LambderCrashDetail;
 };
@@ -85,14 +89,19 @@ export type LambderInvokeDeliveryFailure = LambderInvokeFailureFields & {
  * caller's LambderApiOutcome is discriminated the same way.
  *
  * `error`, `logList` and `cookies` are on every arm, and `status`,
- * `errorMessage` and `retryAfterSeconds` are there whenever an answer came
+ * `refusal` and `retryAfterSeconds` are there whenever an answer came
  * back to read them from.
  */
-export type LambderInvokeFailure = LambderInvokeValidationFailure | LambderInvokeCrashFailure | LambderInvokePayloadTooLargeFailure | LambderInvokeEnvelopeFailure | LambderInvokeDeliveryFailure;
-export type LambderInvokeOutcome<T> = {
+export type LambderInvokeFailure<TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = LambderInvokeValidationFailure<TMessage> | LambderInvokeCrashFailure<TMessage> | LambderInvokePayloadTooLargeFailure<TMessage> | LambderInvokeEnvelopeFailure<TMessage> | LambderInvokeDeliveryFailure<TMessage>;
+/**
+ * An invoke's result: the callee handler's output on success (never null,
+ * an output being an object or an array), or a failure whose refusal
+ * narrows on the codes the endpoint declares.
+ */
+export type LambderInvokeOutcome<T, TMessage extends LambderUncheckedRefusalMessage = LambderUncheckedRefusalMessage> = {
     ok: true;
     payload: T;
-    response: LambderApiEnvelopeBody<T>;
+    response: LambderApiSuccessEnvelope<T>;
     logList: unknown[];
     /**
      * The answer's Set-Cookie values. A caller carrying a user's session
@@ -102,14 +111,14 @@ export type LambderInvokeOutcome<T> = {
      * tokens themselves.
      */
     cookies: string[];
-} | LambderInvokeFailure;
+} | LambderInvokeFailure<TMessage>;
 export type LambderInvokeErrorInit = {
     message: string;
     reason: LambderInvokeFailureReason;
     apiName: string;
     functionName: string;
     status?: number;
-    errorMessage?: LambderAppRefusalMessage;
+    refusal?: LambderUncheckedRefusalMessage;
     crash?: LambderCrashDetail;
     functionError?: LambderInvokeFunctionError;
     logList: unknown[];
@@ -132,7 +141,7 @@ export declare class LambderInvokeError extends Error {
     readonly apiName: string;
     readonly functionName: string;
     readonly status?: number;
-    readonly errorMessage?: LambderAppRefusalMessage;
+    readonly refusal?: LambderUncheckedRefusalMessage;
     readonly crash?: LambderCrashDetail;
     readonly functionError?: LambderInvokeFunctionError;
     readonly logList: unknown[];

package/dist/invoke/LambderInvokeOutcome.js

@@ -25,7 +25,7 @@ export class LambderInvokeError extends Error {
     apiName;
     functionName;
     status;
-    errorMessage;
+    refusal;
     crash;
     functionError;
     logList;
@@ -41,7 +41,7 @@ export class LambderInvokeError extends Error {
         this.apiName = init.apiName;
         this.functionName = init.functionName;
         this.status = init.status;
-        this.errorMessage = init.errorMessage;
+        this.refusal = init.refusal;
         this.crash = init.crash;
         this.functionError = init.functionError;
         this.logList = init.logList;
@@ -100,8 +100,8 @@ export const describeFailure = (init) => {
         return init.crash.message;
     if (init.functionError)
         return `${init.functionError.errorType ?? "FunctionError"}: ${init.functionError.errorMessage ?? "the function failed"}`;
-    if (init.errorMessage !== undefined)
-        return init.errorMessage.content;
+    if (init.refusal !== undefined)
+        return init.refusal.content;
     if (init.reason === 'validation')
         return "the callee rejected the input";
     if (init.reason === 'versionExpired')

package/dist/mock/LambderMockApp.d.ts

@@ -2,6 +2,8 @@ import type { z } from "zod";
 import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
 import { type LambderApiRequest } from "../api/LambderApiRequest.js";
 import { type LambderApiAnswer } from "../api/LambderApiAnswer.js";
+import { type LambderDeclaredRefuse, type LambderRefusalMessage } from "../shared/wire/LambderApiRefusal.js";
+import { type LambderDeclaredVocabulary, type LambderHandlerRefusalsOf, type LambderRefusalVocabulary, type LambderRefusalVocabularyChecks } from "../api/LambderApiRefusals.js";
 import { type LambderApiTransport, type LambderApiTransportRequest } from "../shared/transport/LambderApiTransport.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import { type LambderApiGuard, type LambderGuardBuilder } from "../api/LambderApiGuards.js";
@@ -11,7 +13,7 @@ import { LambderMemorySessionStore } from "../stores/LambderMemorySessionStore.j
 import LambderSessionManager, { type LambderCreatedSession } from "../session/LambderSessionManager.js";
 import type { LambderMockAppOptions, LambderMockIdempotencyOptions, LambderMockTransport, LambderMockTransportOptions } from "./LambderMockCreateOptions.js";
 import type { LambderApiOptionEntry, LambderGuardDeclarationEntry } from "../shared/wire/LambderApiOptionEntries.js";
-import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, LambderMockEntryInput, LambderMockFailure, LambderMockFailureReason, LambderMockHandler, LambderMockLatency, LambderMockListener, LambderMockPublicNames, LambderMockRateLimitPolicies, LambderMockRegistryCheck, LambderMockRestEntry, LambderMockSessionCallContext, LambderMockSessionNames, LambderMockSlice, LambderMockOverride } from "./LambderMockTypes.js";
+import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, LambderMockEntryInput, LambderMockFailure, LambderMockFailureReason, LambderMockHandler, LambderMockLatency, LambderMockListener, LambderMockPublicNames, LambderMockRateLimitPolicies, LambderMockRegistryCheck, LambderMockRestEntry, LambderMockSessionCallContext, LambderMockSessionNames, LambderMockSlice, LambderMockOverride, LambderMockRefusalsOf } from "./LambderMockTypes.js";
 /**
  * The mock runtime: the API core (LambderApiPipeline, the same class the
  * Lambda server runs) over memory stores, with typed mock handlers and mock
@@ -26,8 +28,10 @@ import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, L
  * which fixes the contract and session types first so everything else is
  * inferred from the options. `TDerived` is true for a mock created with the
  * generated `apiOptions` table, whose entries are their handlers alone.
+ * `TVocabulary` and `TCodesRequired` are the refusal vocabulary the init
+ * declared (declareRefusals), which types every handler's ctx.refuse.
  */
-export declare class LambderMockApp<C extends LambderApiContractShape, S = any, G extends Record<string, LambderApiGuard<any, any, any>> = {}, TDerived extends boolean = false> {
+export declare class LambderMockApp<C extends LambderApiContractShape, S = any, G extends Record<string, LambderApiGuard<any, any, any>> = {}, TDerived extends boolean = false, TVocabulary extends LambderRefusalVocabulary = never, TCodesRequired extends boolean = false> {
     readonly apiVersion: string | null;
     /** The memory stores, for assertions and reset; null for a subsystem that is off or backed by a store of yours. */
     readonly sessionStore: LambderMemorySessionStore<S> | null;
@@ -65,9 +69,17 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
     private readonly registry;
     /** The server's declared options per API, when create() was given the generated table; the entries' declarations come from here. */
     private readonly apiOptions;
+    /** The server's guard declarations, when create() was given the generated table: the refusal codes a declared guard adds to an entry. */
+    private readonly guardDeclarations;
+    /** The server's refusal vocabulary, when create() was given the generated table: whether each code an entry may refuse with carries data. */
+    private readonly refusalVocabulary;
+    /** Whether every refusal an entry answers with has to name a code, as the server's declareRefusals() requireCodes. */
+    private readonly requireRefusalCodes;
     /** The jars the runtime owns and what it planted in document.cookie (see LambderMockBrowserCookies). */
     private readonly browserCookies;
-    constructor(options: LambderMockAppOptions<C, S, G, LambderMockRateLimitPolicies<S>, boolean | LambderMockIdempotencyOptions<S>, {}, Record<string, LambderApiOptionEntry> | undefined>);
+    constructor(options: LambderMockAppOptions<C, S, G, LambderMockRateLimitPolicies<S>, boolean | LambderMockIdempotencyOptions<S>, {}, Record<string, LambderApiOptionEntry> | undefined>, 
+    /** The vocabulary the init declared, or null: what initLambderMock().declareRefusals() passes on. */
+    declared?: LambderDeclaredVocabulary<TVocabulary, TCodesRequired> | null);
     /**
      * The registration-time checks every entry goes through, mocked or not:
      * the ones the server runs on a definition, and the mock's own "a session
@@ -87,13 +99,23 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * the compiler did not see.
      */
     private declaredOptionsOf;
+    /**
+     * The codes an entry may refuse with, read off the generated tables (its
+     * own from apiOptions, its guards' from guardDeclarations), each resolved
+     * through the vocabulary the init declared, exactly as the server
+     * resolves its own: schema, status and flag. An entry that declares
+     * guards needs the guardDeclarations table, and one with any code needs
+     * the vocabulary; a code the tables name that the vocabulary lacks means
+     * the two describe different servers.
+     */
+    private declaredRefusalsOf;
     /** The mode the apiOptions table gives a name, or null without a table or for a name it does not hold. */
     private declaredModeOf;
     private buildEntry;
     /** A mock for a public endpoint: a handler, or the handler with the endpoint's declarations restated. */
-    publicApi<K extends LambderMockPublicNames<C>, TInputSchema extends z.ZodType = z.ZodType>(name: K, entry: LambderMockEntryInput<C, K, S, G, TInputSchema, TDerived>): LambderMockEntry<C, K>;
+    publicApi<K extends LambderMockPublicNames<C>, TInputSchema extends z.ZodType = z.ZodType>(name: K, entry: LambderMockEntryInput<C, K, S, G, TInputSchema, TDerived, TVocabulary, TCodesRequired>): LambderMockEntry<C, K>;
     /** A mock for a session endpoint: the pipeline fetches the session before the handler runs, and refuses without one. */
-    sessionApi<K extends LambderMockSessionNames<C>, TInputSchema extends z.ZodType = z.ZodType>(name: K, entry: LambderMockEntryInput<C, K, S, G, TInputSchema, TDerived>): LambderMockEntry<C, K>;
+    sessionApi<K extends LambderMockSessionNames<C>, TInputSchema extends z.ZodType = z.ZodType>(name: K, entry: LambderMockEntryInput<C, K, S, G, TInputSchema, TDerived, TVocabulary, TCodesRequired>): LambderMockEntry<C, K>;
     /**
      * A public endpoint deliberately left without a mock; a call answers the
      * notMocked refusal carrying the reason.
@@ -162,7 +184,7 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * an override one `it` scoped cannot drop the one a describe put in place
      * around it.
      */
-    override<K extends keyof C & string>(name: K, handler: LambderMockHandler<C, K, S, G>): LambderMockOverride;
+    override<K extends keyof C & string>(name: K, handler: LambderMockHandler<C, K, S, G, TVocabulary, TCodesRequired>): LambderMockOverride;
     /** Puts every overridden handler back, however deeply they were stacked. */
     restoreOverrides(): void;
     /** The registered endpoint names. */
@@ -188,10 +210,10 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * restore, and for a session endpoint the session read).
      */
     private restNotMockedEntry;
-    /** The next call to the endpoint fails this way; several calls queue in order. */
-    failNext(apiName: keyof C & string, failure: LambderMockFailure | LambderMockFailureReason): void;
+    /** The next call to the endpoint fails this way; several calls queue in order. An injected refusal names one of the endpoint's declared codes, its data as a handler raises it (see LambderMockRefusalsOf), and is checked and sent as a real one is. */
+    failNext<K extends keyof C & string>(apiName: K, failure: LambderMockFailure<LambderRefusalMessage<LambderMockRefusalsOf<C, K, TVocabulary>>> | LambderMockFailureReason): void;
     /** Every call to the endpoint fails this way until cleared with null. */
-    setFailure(apiName: keyof C & string, failure: LambderMockFailure | LambderMockFailureReason | null): void;
+    setFailure<K extends keyof C & string>(apiName: K, failure: LambderMockFailure<LambderRefusalMessage<LambderMockRefusalsOf<C, K, TVocabulary>>> | LambderMockFailureReason | null): void;
     /** Every call rejects at the transport, as with no network at all. */
     setOffline(offline: boolean): void;
     setLatency(latency: LambderMockLatency): void;
@@ -313,22 +335,55 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
     }, options?: LambderMockTransportOptions): LambderMockTransport;
 }
 /**
- * Fixes the contract and session data types, then hands out the guard
- * builder bound to the mock's contexts and the create() that infers
- * everything else (the guard map, the rate-limit policies) from its options.
- * Curried for the same reason initLambder is: TypeScript type arguments are
- * all-or-nothing per call.
- *
- * ```ts
- * const mock = initLambderMock<ApiContractType, SessionData>();
- * const mockApp = mock.create({
- *     apiVersion: "1.4.0",
- *     sessions: true,
- *     guards: { tenant: mock.guard({ guardInput: z.object({ tenantId: z.uuid() }), session: true, handler: ... }) },
- * });
- * ```
+ * The mock's entry point: fixes the contract and session types, and hands
+ * out the builders and create() that share them. `declareRefusals()` binds
+ * the server's refusal vocabulary too, the same object the server's init
+ * declares, so a mock handler's ctx.refuse takes a code's data in the
+ * schema's input form and the mock parses it exactly as the server does.
  */
 export declare const initLambderMock: <C extends LambderApiContractShape, S = any>() => {
+    /**
+     * Declares the server's refusal vocabulary on the mock: the same object,
+     * and the same `requireCodes`, the server's init declares, imported from
+     * shared code (codes, zod schemas, statuses and flags hold nothing
+     * secret). Given, every refusal an entry answers with is checked and sent
+     * as the server would send it: the code among the codes the tables give
+     * the entry, its data parsed through the code's schema from the input
+     * form, and the declaration's status and flag. An entry whose tables name
+     * a code needs it.
+     */
+    declareRefusals<const TVocabulary extends LambderRefusalVocabulary, const TRequireCodes extends boolean = false>(refusals: TVocabulary & LambderRefusalVocabularyChecks<TVocabulary>, options?: {
+        requireCodes?: TRequireCodes;
+    }): {
+        /** Builds a mock guard: the server guard's shape, the handler seeing the mock's contexts. */
+        guard: LambderGuardBuilder<LambderMockCallContext<S>, LambderMockSessionCallContext<S>>;
+        /**
+         * Builds a mock rate-limit key, the counterpart of `guard`. Bound to the
+         * mock's own call context, because the server's lambderRateLimitKey() is
+         * bound to the render context and a handler written with it compiles here
+         * while reading fields the mock context does not have.
+         */
+        rateLimitKey: import("../api/LambderApiRateLimits.js").LambderRateLimitKeyBuilder<LambderMockCallContext<S>>;
+        /**
+         * refuse() typed to the vocabulary the mock declared, for a mock guard or
+         * a helper of the mock with no endpoint in hand: `code` is one of its
+         * codes and `data` the schema's input form, parsed as the server parses
+         * it. The free refuse() where the mock declared none.
+         */
+        refuse: [TVocabulary] extends [never] ? (content: string, options?: import("../shared/wire/LambderApiRefusal.js").LambderRefuseOptions) => never : LambderDeclaredRefuse<LambderHandlerRefusalsOf<TVocabulary, keyof TVocabulary & string>, TRequireCodes>;
+        /**
+         * The mock app, with the guard map and the rate-limit policies inferred
+         * from the options.
+         *
+         * `const` on each of them pins a restatement to the contract, at a cost:
+         * inferring a generic from an object literal switches excess-property
+         * checking off for the whole literal, nested objects included, so a typo
+         * inside `rateLimits.policies` or `idempotency` would compile and be
+         * dropped. `I` exists for the same reason `P` does, and
+         * LambderMockSurplusKeys puts the error back on the key.
+         */
+        create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, const D extends Record<string, LambderGuardDeclarationEntry> = {}, const A extends Record<string, LambderApiOptionEntry> | undefined = undefined>(options: LambderMockAppOptions<C, S, G, P, I, D, A>): LambderMockApp<C, S, G, [A] extends [undefined] ? false : true, TVocabulary, TRequireCodes>;
+    };
     /** Builds a mock guard: the server guard's shape, the handler seeing the mock's contexts. */
     guard: LambderGuardBuilder<LambderMockCallContext<S>, LambderMockSessionCallContext<S>>;
     /**
@@ -338,6 +393,13 @@ export declare const initLambderMock: <C extends LambderApiContractShape, S = an
      * while reading fields the mock context does not have.
      */
     rateLimitKey: import("../api/LambderApiRateLimits.js").LambderRateLimitKeyBuilder<LambderMockCallContext<S>>;
+    /**
+     * refuse() typed to the vocabulary the mock declared, for a mock guard or
+     * a helper of the mock with no endpoint in hand: `code` is one of its
+     * codes and `data` the schema's input form, parsed as the server parses
+     * it. The free refuse() where the mock declared none.
+     */
+    refuse: (content: string, options?: import("../shared/wire/LambderApiRefusal.js").LambderRefuseOptions) => never;
     /**
      * The mock app, with the guard map and the rate-limit policies inferred
      * from the options.
@@ -349,5 +411,5 @@ export declare const initLambderMock: <C extends LambderApiContractShape, S = an
      * dropped. `I` exists for the same reason `P` does, and
      * LambderMockSurplusKeys puts the error back on the key.
      */
-    create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, const D extends Record<string, LambderGuardDeclarationEntry> = {}, const A extends Record<string, LambderApiOptionEntry> | undefined = undefined>(options: LambderMockAppOptions<C, S, G, P, I, D, A>): LambderMockApp<C, S, G, [A] extends [undefined] ? false : true>;
+    create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, const D extends Record<string, LambderGuardDeclarationEntry> = {}, const A extends Record<string, LambderApiOptionEntry> | undefined = undefined>(options: LambderMockAppOptions<C, S, G, P, I, D, A>): LambderMockApp<C, S, G, [A] extends [undefined] ? false : true, never, false>;
 };