lambder 11.0.1 → 12.0.1

package/dist/mock/LambderMockApp.js

@@ -93,6 +93,8 @@ export class LambderMockApp {
     registry = new LambderMockEntryRegistry();
     /** The server's declared options per API, when create() was given the generated table; the entries' declarations come from here. */
     apiOptions;
+    /** The mock's own guards as create() was given them: which of them need a session, for an entry's mode without the apiOptions table. */
+    mockGuards;
     /** The server's guard declarations, when create() was given the generated table: the refusal codes a declared guard adds to an entry. */
     guardDeclarations;
     /** The server's refusal vocabulary, when create() was given the generated table: whether each code an entry may refuse with carries data. */
@@ -106,6 +108,7 @@ export class LambderMockApp {
     declared = null) {
         this.apiVersion = options.apiVersion ?? null;
         this.apiOptions = options.apiOptions ?? null;
+        this.mockGuards = options.guards ?? null;
         this.guardDeclarations = options.guardDeclarations ?? null;
         this.refusalVocabulary = declared?.vocabulary ?? null;
         this.requireRefusalCodes = declared?.requireCodes ?? false;
@@ -220,23 +223,33 @@ export class LambderMockApp {
     }
     /**
      * The table's entry for an endpoint, when create() was given one: null
-     * without a table, and a throw for a name the table does not hold or an
-     * entry registered under the other mode. The compiler already refuses
-     * both against the contract; this is where a stale table meets a caller
-     * the compiler did not see.
+     * without a table, and a throw for a name the table does not hold. The
+     * compiler already refuses it against the contract; this is where a
+     * stale table meets a caller the compiler did not see.
      */
-    declaredOptionsOf(name, mode) {
+    declaredOptionsOf(name) {
         if (!this.apiOptions)
             return null;
         const declared = Object.prototype.hasOwnProperty.call(this.apiOptions, name) ? this.apiOptions[name] : undefined;
         if (!declared) {
             throw new Error(`LambderMockApp: "${name}" has no entry in the apiOptions table given to create(). The table predates this endpoint: regenerate it with writeApiOptions.`);
         }
-        if (declared.mode !== mode) {
-            throw new Error(`LambderMockApp: "${name}" is a ${declared.mode} endpoint in the apiOptions table, registered here as a ${mode} one.`);
-        }
         return declared;
     }
+    /**
+     * An entry's mode, by the server's rule: a session endpoint when one of
+     * its guards needs a session. The guards are the apiOptions table's when
+     * create() was given one (which records the mode it came to as well), and
+     * otherwise the ones the entry restates, each read off the guardDeclarations
+     * table or the mock's own guards.
+     */
+    modeOf(declared, restatedGuards) {
+        if (declared)
+            return declared.mode;
+        const needsSession = (guard) => (this.guardDeclarations && Object.prototype.hasOwnProperty.call(this.guardDeclarations, guard) && this.guardDeclarations[guard].session === true)
+            || (this.mockGuards && Object.prototype.hasOwnProperty.call(this.mockGuards, guard) && this.mockGuards[guard].session === true);
+        return toGuardEntries(restatedGuards).some(({ name: guard }) => needsSession(guard)) ? "session" : "public";
+    }
     /**
      * The codes an entry may refuse with, read off the generated tables (its
      * own from apiOptions, its guards' from guardDeclarations), each resolved
@@ -276,9 +289,10 @@ export class LambderMockApp {
             return null;
         return this.apiOptions[name].mode;
     }
-    buildEntry(name, mode, input) {
+    buildEntry(name, input) {
         const options = (typeof input === "function" ? { handler: input } : input);
-        const declared = this.declaredOptionsOf(name, mode);
+        const declared = this.declaredOptionsOf(name);
+        const mode = this.modeOf(declared, options.guards);
         if (declared) {
             // A caller the compiler did not see (a JavaScript slice, a cast)
             // would otherwise have its restatement silently lose to the table.
@@ -306,32 +320,34 @@ export class LambderMockApp {
         const handler = options.handler;
         return { name, mode, definition, handler: async (ctx) => await handler(ctx), notMockedReason: null };
     }
-    /** A mock for a public endpoint: a handler, or the handler with the endpoint's declarations restated. */
-    publicApi(name, entry) {
-        return this.buildEntry(name, "public", entry);
-    }
-    /** A mock for a session endpoint: the pipeline fetches the session before the handler runs, and refuses without one. */
-    sessionApi(name, entry) {
-        return this.buildEntry(name, "session", entry);
-    }
     /**
-     * A public endpoint deliberately left without a mock; a call answers the
-     * notMocked refusal carrying the reason.
-     *
-     * Public and session get separate builders, as publicApi and sessionApi
-     * do, because the refusal runs through the pipeline so the steps BEFORE
-     * dispatch still happen, and the session read is one of them. Were every
-     * not-mocked endpoint public, a session endpoint with no session would
-     * answer "not mocked" where the server answers sessionExpired, and its
-     * events and call log would carry the wrong mode. The contract is a type,
-     * so the mode cannot be recovered at runtime: the builder has to say it.
+     * A mock for an endpoint: a handler, or the handler with the endpoint's
+     * declarations restated. Its mode is the server's (see modeOf): a
+     * session endpoint's session is fetched before the handler runs, and a
+     * call without one is refused as on the server.
      */
-    notMocked(name, reason) {
-        return this.buildNotMockedEntry(name, "public", reason);
+    api(name, entry) {
+        return this.buildEntry(name, entry);
     }
-    /** A session endpoint deliberately left without a mock: the session is still read, and refused before the notMocked refusal. */
-    sessionNotMocked(name, reason) {
-        return this.buildNotMockedEntry(name, "session", reason);
+    /**
+     * An endpoint deliberately left without a mock; a call answers the
+     * notMocked refusal carrying the reason. The refusal runs through the
+     * pipeline, so the steps before dispatch still happen, the session read
+     * among them, under the server's mode (see modeOf): a signed-out call to
+     * a session endpoint answers sessionExpired as on the server. Without the
+     * apiOptions table a session endpoint restates its guards to say so,
+     * `notMocked(name, { reason, guards })`; no guard runs.
+     */
+    notMocked(name, input) {
+        const { reason, guards } = (typeof input === "string" ? { reason: input } : input);
+        const declared = this.declaredOptionsOf(name);
+        if (declared && guards !== undefined) {
+            throw new Error(`LambderMockApp: "${name}" restates its guards option, which the apiOptions table given to create() already declares. Leave it out of the entry.`);
+        }
+        const mode = this.modeOf(declared, guards);
+        const definition = { name, mode };
+        this.assertEntryRegistration(definition);
+        return { name, mode, definition, handler: null, notMockedReason: reason };
     }
     /**
      * "Everything I did not register is not mocked, for this reason", as an
@@ -356,18 +372,12 @@ export class LambderMockApp {
      * a type), and a call it answers is processed as public: the protocol's
      * pre-pass still runs, so a stale client still hears versionExpired, but
      * a signed-out call to an unmocked session endpoint answers "not mocked"
-     * where the server answers sessionExpired. Declare an endpoint whose
-     * signed-out path a test cares about with sessionNotMocked there.
+     * where the server answers sessionExpired. Give create() the table where
+     * a test cares about that path.
      */
     restNotMocked(reason) {
         return { restNotMockedReason: reason };
     }
-    buildNotMockedEntry(name, mode, reason) {
-        this.declaredOptionsOf(name, mode);
-        const definition = { name, mode };
-        this.assertEntryRegistration(definition);
-        return { name, mode, definition, handler: null, notMockedReason: reason };
-    }
     /** The entries of one module as a slice, keyed by name. Two entries for one endpoint is an error here. */
     apiSlice(...entries) {
         const slice = {};
@@ -809,10 +819,7 @@ export class LambderMockApp {
         // the "saved" record with no call), a Date would stay a Date and a
         // key set to undefined keep its place, none of which a server sees.
         const envelope = JSON.parse(JSON.stringify(buildTransportEnvelope(transportRequest)));
-        const request = readApiEnvelope(envelope, info);
-        if (!request)
-            throw new Error("LambderMockApp: the transport request names no api.");
-        return request;
+        return readApiEnvelope(envelope, info, transportRequest.apiName);
     }
     /** One call from a transport request to its answer: what the mock transport and the adapters call. */
     async handle(transportRequest) {

package/dist/mock/LambderMockCreateOptions.d.ts

@@ -16,7 +16,7 @@ import type { LambderSessionStore } from "../shared/contracts/LambderSessionStor
 import type { LambderSessionDataRefreshConfig } from "../session/LambderSessionManager.js";
 import type { LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import type { LambderSessionCrypto } from "../session/LambderSessionCrypto.js";
-import type { LambderMockCallContext, LambderMockGuards, LambderMockLatency, LambderMockRateLimitPolicies, LambderMockSessionCallContext, LambderMockSurplusKeys } from "./LambderMockTypes.js";
+import type { LambderMockCallContext, LambderMockGuards, LambderMockLatency, LambderMockRateLimitPolicies, LambderMockSessionCallContext, LambderMockSessionGuardsCheck, LambderMockSurplusKeys } from "./LambderMockTypes.js";
 export type LambderMockSessionsOptions<S> = {
     /** Where the mock's sessions rest. Default: a fresh LambderMemorySessionStore. */
     store?: LambderSessionStore<S>;
@@ -158,9 +158,9 @@ type LambderMockGuardsAgree<G, D> = {
 type LambderMockGuardsOption<C, S, G, D> = [
     LambderContractGuardNames<C>
 ] extends [never] ? {
-    guards?: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G> & LambderMockGuardsAgree<G, NoInfer<D>>;
+    guards?: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G> & LambderMockGuardsAgree<G, NoInfer<D>> & LambderMockSessionGuardsCheck<C, G>;
 } : {
-    guards: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G> & LambderMockGuardsAgree<G, NoInfer<D>>;
+    guards: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G> & LambderMockGuardsAgree<G, NoInfer<D>> & LambderMockSessionGuardsCheck<C, G>;
 };
 /**
  * The sessions, idempotency and rateLimits options: each required whenever
@@ -225,10 +225,9 @@ export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicie
      * exports them (`apiOptions`). Given, every entry's guards, rateLimit and
      * idempotency are read off the table rather than restated: an entry is
      * its handler (and an input schema, if it has one), a restated option is
-     * a compile error, and an endpoint whose mode the table and the builder
-     * disagree on is refused at registration. A restNotMocked answer reads
-     * the endpoint's mode off the table too, so a session endpoint nothing
-     * mocks still reads the session first. The table has to cover the
+     * a compile error, and the entry takes the table's mode. A notMocked
+     * entry and a restNotMocked answer read the endpoint's mode off the table
+     * too, so a session endpoint nothing mocks still reads the session first. The table has to cover the
      * contract (see LambderMockApiOptionsCover).
      */
     apiOptions?: A & LambderMockApiOptionsCover<C>;

package/dist/mock/LambderMockTypes.d.ts

@@ -6,7 +6,7 @@
  * the contract stays a type-only import in the consuming app.
  */
 import type { z } from "zod";
-import type { LambderApiMode, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractGuardInputsOf, LambderContractGuardNames, LambderContractGuardsOf, LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractMode, LambderContractRateLimitOf } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiMode, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractGuardInputsOf, LambderContractGuardNames, LambderContractGuardsOf, LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractMode, LambderContractRateLimitOf, LambderGuardNamesIn } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiGuard, LambderGuardDataOf, LambderGuardMetaMap } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderContextRateLimit, LambderContextRateLimitCheck } from "../api/LambderApiRateLimits.js";
 import type { LambderApiCallContext, LambderResponseTools } from "../api/LambderApiCallContext.js";
@@ -105,8 +105,9 @@ export type LambderMockContext<C, K extends keyof C, S, G, TVocabulary = never,
  * the contract declares, plus, for each guardInput-mode guard, a `guardInput`
  * schema whose input is what the contract says a client sends. A guard a
  * public endpoint names may not require a session. A missing name, a schema
- * that parses to something else, or such a session guard fails at the
- * `guards` option.
+ * that parses to something else, or a public endpoint's guard that requires
+ * a session fails at the `guards` option; LambderMockSessionGuardsCheck
+ * holds the session endpoints to the same rule from the other side.
  */
 export type LambderMockGuards<C, S = any> = {
     [N in LambderContractGuardNames<C>]: LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>;
@@ -119,6 +120,33 @@ export type LambderMockGuards<C, S = any> = {
         session?: false;
     };
 };
+/** The guards of a mock guard map that need a session. */
+type LambderMockSessionGuardNames<G> = {
+    [N in keyof G]: G[N] extends {
+        session: true;
+    } ? N : never;
+}[keyof G];
+/** The contract's session endpoints none of whose guards the mock guard map declares `session: true`. */
+type LambderMockSessionEndpointsWithoutSessionGuard<C, G> = {
+    [K in LambderContractKeysWithMode<C, "session">]: [
+        Extract<LambderGuardNamesIn<LambderContractGuardsOf<C, K>>, LambderMockSessionGuardNames<G>>
+    ] extends [never] ? K : never;
+}[LambderContractKeysWithMode<C, "session">];
+/**
+ * The mock guard map held to the server's rule for session endpoints: each
+ * names at least one guard that needs a session. The guards are what make
+ * an endpoint a session one, on the server and in the mock alike, and
+ * without the apiOptions table the mock reads an entry's mode off the guards
+ * it restates, so a session endpoint none of whose mock guards says
+ * `session: true` would run as public: a signed-out call would reach a
+ * handler typed with its session present. The property name is the message
+ * and its value the endpoints at fault.
+ */
+export type LambderMockSessionGuardsCheck<C, G> = [
+    LambderMockSessionEndpointsWithoutSessionGuard<C, G>
+] extends [never] ? unknown : {
+    readonly "lambder: these session endpoints name no mock guard declared session: true, so the mock would run them as public": LambderMockSessionEndpointsWithoutSessionGuard<C, G>;
+};
 export type LambderMockHandler<C, K extends keyof C, S, G, TVocabulary = never, TCodesRequired extends boolean = false> = (ctx: LambderMockContext<C, K, S, G, TVocabulary, TCodesRequired>) => LambderMockOutputOf<C, K> | Promise<LambderMockOutputOf<C, K>>;
 /**
  * The guards field of an entry: required whenever the contract declares any
@@ -230,7 +258,7 @@ export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema ext
     handler: LambderMockHandler<C, K, S, G, TVocabulary, TCodesRequired>;
 };
 /**
- * What publicApi/sessionApi accept. On a mock created with the generated
+ * What api() accepts. On a mock created with the generated
  * `apiOptions` table (`TDerived`), a bare handler or the options without the
  * declarations, for every endpoint. Otherwise a bare handler only for an
  * endpoint the contract declares nothing for, the full options elsewhere, so
@@ -240,6 +268,18 @@ export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema ext
  * bare form.
  */
 export type LambderMockEntryInput<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType, TDerived extends boolean = false, TVocabulary = never, TCodesRequired extends boolean = false> = TDerived extends true ? LambderMockHandler<C, K, S, G, TVocabulary, TCodesRequired> | LambderMockEntryOptions<C, K, S, G, TInputSchema, true, TVocabulary, TCodesRequired> : [LambderContractGuardsOf<C, K> | LambderContractRateLimitOf<C, K> | LambderContractIdempotencyOf<C, K>] extends [never] ? LambderMockHandler<C, K, S, G, TVocabulary, TCodesRequired> | LambderMockEntryOptions<C, K, S, G, TInputSchema, false, TVocabulary, TCodesRequired> : LambderMockEntryOptions<C, K, S, G, TInputSchema, false, TVocabulary, TCodesRequired>;
+/**
+ * What notMocked() accepts: the reason, or, for a session endpoint on a mock
+ * created without the generated `apiOptions` table, the reason with the
+ * endpoint's guards restated. The entry answers before any guard runs, but
+ * its mode is still the server's (the session read before the notMocked
+ * refusal), and without the table only the guards can say it, as they do
+ * for api().
+ */
+export type LambderMockNotMockedInput<C, K extends keyof C, TDerived extends boolean = false> = TDerived extends true ? string : LambderContractMode<C, K> extends "session" ? {
+    reason: string;
+    guards: LambderContractGuardsOf<C, K>;
+} : string;
 /** One registry entry: the endpoint's definition as the pipeline runs it, and its handler (null when registered as not mocked). */
 export type LambderMockEntry<C, K extends keyof C & string> = {
     readonly name: K;
@@ -248,9 +288,6 @@ export type LambderMockEntry<C, K extends keyof C & string> = {
     readonly handler: ((ctx: any) => Promise<unknown>) | null;
     readonly notMockedReason: string | null;
 };
-/** The endpoint names a mock app may register under each mode. */
-export type LambderMockPublicNames<C> = LambderContractKeysWithMode<C, "public">;
-export type LambderMockSessionNames<C> = LambderContractKeysWithMode<C, "session">;
 /** A slice: the entries of one module, keyed by endpoint name. */
 export type LambderMockSlice<C, K extends keyof C & string> = {
     readonly [P in K]: LambderMockEntry<C, P>;

package/dist/mock/lambderMockInvokeTransport.d.ts

@@ -12,17 +12,25 @@ import { type LambderApiRequest } from "../api/LambderApiRequest.js";
  * returned function still fits LambderInvokeTransport.
  */
 export type LambderMockInvokeEvent = {
+    /** The path the call was made to, `{apiPath}/{group}/{action}`. */
+    rawPath?: string | undefined;
     body?: string | undefined;
     isBase64Encoded?: boolean | undefined;
     headers?: Record<string, string | undefined> | undefined;
     cookies?: string[] | undefined;
     requestContext?: {
         http?: {
+            method?: string;
             sourceIp?: string;
         } | undefined;
         domainName?: string;
     } | undefined;
 };
+/** The options of lambderMockInvokeTransport. */
+export type LambderMockInvokeTransportOptions = {
+    /** The apiPath the mocked function serves its calls under, as its LambderInvokeCaller names it. Default: "/api", as there. */
+    apiPath?: string;
+};
 /** What the callee answers with: the Lambda response object LambderInvokeCaller decodes. */
 export type LambderMockInvokeResult = {
     functionError: string | null;
@@ -43,6 +51,6 @@ export type LambderMockInvokeResult = {
  */
 export declare const lambderMockInvokeTransport: (mockApp: {
     handleRequest(request: LambderApiRequest): Promise<LambderApiAnswer>;
-}) => ((event: LambderMockInvokeEvent, options: {
+}, options?: LambderMockInvokeTransportOptions) => ((event: LambderMockInvokeEvent, options: {
     signal?: AbortSignal;
 }) => Promise<LambderMockInvokeResult>);

package/dist/mock/lambderMockInvokeTransport.js

@@ -1,3 +1,5 @@
+import { apiNameOfCallPath } from "../shared/wire/LambderApiNames.js";
+import { DEFAULT_API_PATH } from "../shared/wire/LambderDefaultApiPath.js";
 import { readApiEnvelope, cookieValuesByName, isApiCallContentType, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
 import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 import { base64ToText } from "../shared/util/LambderBase64.js";
@@ -9,7 +11,8 @@ import { normalizeClientIp } from "../shared/util/LambderClientIp.js";
  * can then point its typed invoke caller at a mock of the function it
  * depends on, with the same registry a browser test uses.
  */
-export const lambderMockInvokeTransport = (mockApp) => async (event, { signal }) => {
+export const lambderMockInvokeTransport = (mockApp, options = {}) => async (event, { signal }) => {
+    const apiPath = options.apiPath ?? DEFAULT_API_PATH;
     const rawBody = event.body ?? "";
     const body = event.isBase64Encoded ? base64ToText(rawBody) : rawBody;
     let post = {};
@@ -21,16 +24,21 @@ export const lambderMockInvokeTransport = (mockApp) => async (event, { signal })
     }
     const headers = lowercaseHeaderNames(event.headers);
     const cookies = cookieValuesByName(event.cookies ?? []);
-    // A POST of another type is no API call on the server either. The
-    // address is the one the synthesized event carries in sourceIp, as the
-    // server's createContext reads it; no forwarding header is trusted here
-    // either, so a per-IP limit keys the same address under both adapters.
-    const request = isApiCallContentType(headers) && readApiEnvelope(post, {
+    // A JSON POST to `{apiPath}/{group}/{action}` is a call, as the server's
+    // createContext reads it; anything else (another method or type, a path
+    // outside apiPath) is no API call on the server either, and a mock
+    // serves no routes. The address is the one the synthesized event carries
+    // in sourceIp, as createContext reads it; no forwarding header is trusted
+    // here either, so a per-IP limit keys the same address under both adapters.
+    const apiName = event.requestContext?.http?.method === "POST" && isApiCallContentType(headers)
+        ? apiNameOfCallPath(apiPath, event.rawPath ?? "")
+        : null;
+    const request = apiName !== null && readApiEnvelope(post, {
         headers, cookies,
         ip: normalizeClientIp(event.requestContext?.http?.sourceIp ?? ""),
         host: headers.host || event.requestContext?.domainName || "lambder-invoke",
         ...(signal ? { signal } : {}),
-    });
+    }, apiName);
     if (!request) {
         return { functionError: null, result: { statusCode: 404, headers: { "content-type": "text/plain; charset=utf-8" }, body: "Not found.", isBase64Encoded: false } };
     }

package/dist/mock/lambderMockMswHandler.js

@@ -1,4 +1,5 @@
 import { LambderMockTransportError } from "./LambderMockFailureInjector.js";
+import { apiNameOfCallPath } from "../shared/wire/LambderApiNames.js";
 import { readApiEnvelope, cookieValuesByName, isApiCallContentType, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
 import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
@@ -50,7 +51,9 @@ export const lambderMockMswHandler = (mockApp, options) => {
     // adapter's is, so one address is one counter under a `per: "ip"` limit
     // however it was spelled.
     const clientIp = normalizeClientIp(options.clientIp ?? mockApp.defaultClientIp);
-    const handler = msw.http.post(apiPath, async ({ request }) => {
+    // Every call goes to `{apiPath}/{group}/{action}`; the endpoint is read
+    // off the path as the server reads it (apiNameOfCallPath).
+    const handler = msw.http.post(`${apiPath.replace(/\/+$/, "")}/:group/:action`, async ({ request }) => {
         let post;
         try {
             post = await request.clone().json();
@@ -91,11 +94,12 @@ export const lambderMockMswHandler = (mockApp, options) => {
                     (cookies[name] ??= []).push(value);
             }
         }
+        const apiName = apiNameOfCallPath(new URL(apiPath, url).pathname, url.pathname);
+        if (apiName === null)
+            return undefined;
         const parsed = readApiEnvelope(post, {
             headers, cookies, ip: clientIp, host: url.host, signal: request.signal,
-        });
-        if (!parsed)
-            return undefined;
+        }, apiName);
         // Returning undefined hands the request back to MSW, which tries its
         // other handlers and then the network. Noted on the runtime first:
         // a passthrough that leaves no event and no call-log row is a

package/dist/mock.d.ts

@@ -9,7 +9,7 @@
 export { LambderMockApp, initLambderMock } from "./mock/LambderMockApp.js";
 export { LambderMockTransportError } from "./mock/LambderMockFailureInjector.js";
 export type { LambderMockAppOptions, LambderMockSessionsOptions, LambderMockIdempotencyOptions, LambderMockInvalidInputAnswer, LambderMockTransport, LambderMockTransportOptions } from "./mock/LambderMockCreateOptions.js";
-export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMockContext, LambderMockRefusalsOf, LambderMockGuards, LambderMockHandler, LambderMockEntry, LambderMockEntryOptions, LambderMockEntryInput, LambderMockSlice, LambderMockRestEntry, LambderMockRegistryCheck, LambderMockMissingNames, LambderMockStrayNames, LambderMockDuplicateNames, LambderMockPublicNames, LambderMockSessionNames, LambderMockLatency, LambderMockFailure, LambderMockFailureReason, LambderMockOutcome, LambderMockCallEvent, LambderMockRequestEvent, LambderMockResponseEvent, LambderMockCallRecord, LambderMockListener, LambderMockRateLimitPolicies, LambderMockInputOf, LambderMockOutputOf, LambderMockOverride, } from "./mock/LambderMockTypes.js";
+export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMockContext, LambderMockRefusalsOf, LambderMockGuards, LambderMockHandler, LambderMockEntry, LambderMockEntryOptions, LambderMockEntryInput, LambderMockNotMockedInput, LambderMockSessionGuardsCheck, LambderMockSlice, LambderMockRestEntry, LambderMockRegistryCheck, LambderMockMissingNames, LambderMockStrayNames, LambderMockDuplicateNames, LambderMockLatency, LambderMockFailure, LambderMockFailureReason, LambderMockOutcome, LambderMockCallEvent, LambderMockRequestEvent, LambderMockResponseEvent, LambderMockCallRecord, LambderMockListener, LambderMockRateLimitPolicies, LambderMockInputOf, LambderMockOutputOf, LambderMockOverride, } from "./mock/LambderMockTypes.js";
 export { lambderMockPoliciesFrom } from "./mock/lambderMockPoliciesFrom.js";
 export type { LambderCustomKeyedPolicyNames, LambderMockPolicyKeys } from "./mock/lambderMockPoliciesFrom.js";
 export type { LambderMockGuardShapeOf } from "./mock/LambderMockCreateOptions.js";
@@ -21,7 +21,7 @@ export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js
 export type { LambderMemoryUploadBucketOptions, LambderMemoryUploadObject } from "./stores/LambderMemoryUploadBucket.js";
 export { lambderMockUploadMswHandler } from "./mock/lambderMockUploadMswHandler.js";
 export { lambderMockInvokeTransport } from "./mock/lambderMockInvokeTransport.js";
-export type { LambderMockInvokeEvent, LambderMockInvokeResult } from "./mock/lambderMockInvokeTransport.js";
+export type { LambderMockInvokeEvent, LambderMockInvokeResult, LambderMockInvokeTransportOptions } from "./mock/lambderMockInvokeTransport.js";
 export { LambderCookieJar } from "./shared/transport/LambderCookieJar.js";
 export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTransport.js";
 export type { LambderApiTransport, LambderApiTransportRequest } from "./shared/transport/LambderApiTransport.js";

package/dist/shared/transport/LambderApiTransport.d.ts

@@ -8,6 +8,7 @@ import type { LambderCompressedGzipPayload, LambderCompressedBrotliPayload } fro
  */
 export type LambderApiTransportRequest = {
     apiPath: string;
+    /** The endpoint called, `group.action`: the call goes to `{apiPath}/{group}/{action}` (apiCallPath). */
     apiName: string;
     version?: string;
     /** The caller's signature for this endpoint, out of its LambderApiSignatureMap; absent when it carries no map. */
@@ -90,7 +91,8 @@ export declare const isLambderTransportFailure: (err: unknown) => err is Lambder
 export type LambderApiTransport = (request: LambderApiTransportRequest) => Promise<LambderApiHttpAnswer>;
 /**
  * The fields of the request envelope, in wire order: the one statement of
- * what a call sends, for every sender.
+ * what a call sends, for every sender. The endpoint is not among them: it is
+ * the path the envelope is posted to (apiCallPath).
  *
  * Two senders write it. A transport hands the payload over as a value
  * (buildTransportEnvelope, below); LambderInvokeCaller has already serialized
@@ -101,7 +103,6 @@ export type LambderApiTransport = (request: LambderApiTransportRequest) => Promi
  * the wire would catch.
  */
 export declare const buildEnvelopeFields: (fields: {
-    apiName: string;
     version?: string;
     signature?: string;
     /** The CSRF token, as the envelope names it. */

package/dist/shared/transport/LambderApiTransport.js

@@ -16,7 +16,8 @@ export class LambderTransportFailure extends Error {
 export const isLambderTransportFailure = (err) => err instanceof Error && err.isLambderTransportFailure === true;
 /**
  * The fields of the request envelope, in wire order: the one statement of
- * what a call sends, for every sender.
+ * what a call sends, for every sender. The endpoint is not among them: it is
+ * the path the envelope is posted to (apiCallPath).
  *
  * Two senders write it. A transport hands the payload over as a value
  * (buildTransportEnvelope, below); LambderInvokeCaller has already serialized
@@ -27,7 +28,6 @@ export const isLambderTransportFailure = (err) => err instanceof Error && err.is
  * the wire would catch.
  */
 export const buildEnvelopeFields = (fields) => ({
-    apiName: fields.apiName,
     version: fields.version,
     ...(fields.signature !== undefined ? { signature: fields.signature } : {}),
     token: fields.token,
@@ -42,7 +42,6 @@ export const buildEnvelopeFields = (fields) => ({
  * runtime read one shape.
  */
 export const buildTransportEnvelope = (request) => buildEnvelopeFields({
-    apiName: request.apiName,
     version: request.version,
     signature: request.signature,
     token: request.token,

package/dist/shared/transport/lambderCookieJarTransport.js

@@ -1,5 +1,6 @@
 import { DEFAULT_SESSION_CSRF_COOKIE_KEY } from "../wire/LambderSessionCookieNames.js";
 import { resolveApiPathTarget } from "./LambderApiTransport.js";
+import { apiCallPath } from "../wire/LambderApiNames.js";
 /**
  * Makes any transport carry a cookie jar the way a browser carries its
  * cookies: the jar's cookies ride on every request, the answer's Set-Cookie
@@ -36,7 +37,7 @@ export const lambderCookieJarTransport = (inner, options) => {
         // absolute cross-origin apiPath. siteHost is "" outside a browser, and
         // an empty host would scope every cookie to nothing while claiming to
         // scope it.
-        const target = resolveApiPathTarget(request.apiPath);
+        const target = resolveApiPathTarget(apiCallPath(request.apiPath, request.apiName));
         const cookieScope = {
             host: target.host ?? options.host ?? (request.siteHost || undefined),
             path: target.path,

package/dist/shared/util/LambderTypeUtilities.d.ts

@@ -35,7 +35,7 @@ export type LambderReadonlyDeep<T, TDepth extends unknown[] = []> = TDepth["leng
  * name, of "this one required and the rest optional".
  *
  * An all-optional map is inhabited by `{}`, which would let `guards: {}`
- * satisfy requireSessionApiGuards / requirePublicApiGuards at the type level
+ * satisfy requireApiGuards at the type level
  * while declaring no guard: the option is present, so the required-field
  * check passes, and it normalizes to zero entries, so nothing runs. Requiring
  * the chosen key also rejects `{ theGuard: undefined }`, which an optional

package/dist/shared/wire/LambderApiContract.d.ts

@@ -1,12 +1,12 @@
 /**
  * Lambder API Contract System
  *
- * Contracts are built via method chaining and inferred using typeof lambder.ApiContract
+ * Contracts are the endpoint declarations an instance registered, read with typeof lambder.ApiContract
  */
 import type { LambderCrashDetail } from "./LambderCrashDetail.js";
 import type { LambderUncheckedRefusalMessage, LambderPlainRefusalMessage, LambderRefusalMessage } from "./LambderApiRefusal.js";
 import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "./LambderApiOptionValues.js";
-/** Whether an endpoint runs without a session or requires one (addApi versus addSessionApi). */
+/** Whether an endpoint runs without a session or requires one: "session" exactly when one of its guards needs a session. */
 export type LambderApiMode = "public" | "session";
 /**
  * Base shape for API contracts: what LambderCaller, LambderInvokeCaller and
@@ -15,7 +15,7 @@ export type LambderApiMode = "public" | "session";
 export type LambderApiContractShape = Record<string, {
     input: any;
     output: any;
-    /** "public" (addApi) or "session" (addSessionApi). */
+    /** "public", or "session" when one of its guards needs a session. */
     mode?: LambderApiMode;
     /** Present when the API declares guardInput-mode guards: guard name -> value the client must send via options.guardInputs. */
     guardInputs?: any;
@@ -149,7 +149,7 @@ export type LambderJsonOf<T> = unknown extends T ? T : T extends LambderJsonValu
     [K in keyof TKeyed as K extends string | number ? (string extends K ? K : number extends K ? K : [LambderJsonOf<TKeyed[K]>] extends [never] ? never : K) : never]: LambderJsonOf<TKeyed[K]>;
 } : never : never;
 /**
- * One contract entry as addApi/addSessionApi record it: the payload types,
+ * One contract entry as defineApi records it: the payload types,
  * the mode, and every declarative option exactly as written. Options that
  * were not written are absent rather than undefined, so `keyof` an entry
  * lists only what the endpoint declared.
@@ -180,20 +180,6 @@ export type LambderContractEntry<In, Out, Mode extends LambderApiMode, GuardInpu
 }) & ([Idempotency] extends [never] ? {} : {
     idempotency: Idempotency;
 });
-/**
- * Merges a new entry into the contract during chaining.
- *
- * The contract is therefore an intersection one member deep per endpoint, and
- * every `C[K]` read generically (a typed caller, a mock registry, a test
- * visitor) resolves the property across all of them. That costs nothing
- * worth measuring in a small app and most of a large client's type check,
- * which is what writeApiContract (lambder/build) is for: it writes the
- * contract out as one object type with plain members, for clients to import
- * instead of the server.
- */
-export type LambderMergeContract<Old, Name extends string, Entry> = Old & {
-    [K in Name]: Entry;
-};
 /** Guard names referenced by a guards option, whichever of its three forms is used. */
 export type LambderGuardNamesIn<TOpt> = TOpt extends string ? TOpt : TOpt extends readonly (infer N extends string)[] ? N : TOpt extends object ? keyof TOpt & string : never;
 /** The endpoint's mode; a contract written without one admits either. */

package/dist/shared/wire/LambderApiContract.js

@@ -1,6 +1,6 @@
 /**
  * Lambder API Contract System
  *
- * Contracts are built via method chaining and inferred using typeof lambder.ApiContract
+ * Contracts are the endpoint declarations an instance registered, read with typeof lambder.ApiContract
  */
 export {};

package/dist/shared/wire/LambderApiGroupCalls.d.ts

@@ -0,0 +1,31 @@
+/** The groups a contract's endpoint names hold: the part of each before its dot. */
+export type LambderContractGroupsOf<TContract> = keyof TContract extends infer TName ? (TName extends `${infer TGroup}.${string}` ? TGroup : never) : never;
+/** The endpoint names of one group. */
+export type LambderContractNamesInGroup<TContract, TGroup extends string> = Extract<keyof TContract, `${TGroup}.${string}`> & string;
+/** An endpoint name's action: the part after its dot. */
+export type LambderContractActionOf<TName> = TName extends `${string}.${infer TAction}` ? TAction : never;
+/** A call made through a group: the endpoint's name, and the arguments as the call site passed them. */
+type LambderGroupCallRunner = (apiName: string, args: unknown[]) => unknown;
+/**
+ * The caller, answering for each group a contract could name besides its
+ * own members. A member the caller has (a method, a field) is always the
+ * caller's; a name that could be a group (see isGroupName: an identifier no
+ * caller member has) is one; anything else a runtime or a framework asks of
+ * an object (then, toJSON, a symbol, `__v_isRef`) is what the caller itself
+ * answers, so a caller is never mistaken for a promise, a ref or a
+ * serializable record.
+ *
+ * A caller keeps its state in #private fields, which no property name
+ * reaches, so a group may take any name its public members leave free. Such
+ * a field is readable only on the caller itself, never through this proxy,
+ * so a member is read and a method run on the caller; a method that returns
+ * the caller (setTransport) hands back the proxy, groups and all.
+ *
+ * A group answers the same way one level down: an ordinary object's own
+ * members (toString, valueOf, hasOwnProperty) are an ordinary object's, so
+ * converting a group to a string or asking it what it holds calls no
+ * endpoint; any other name that could be an action (see isActionName) is
+ * one. A group is read-only, like the type that describes it.
+ */
+export declare const withApiGroupCalls: <TCaller extends object>(caller: TCaller, call: LambderGroupCallRunner, outcome: LambderGroupCallRunner) => TCaller;
+export {};