lambder 11.0.1 → 12.0.1

package/CHANGELOG.md

@@ -9,6 +9,160 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [12.0.1] - 2026-09-30
+
+A major: endpoints are values. An app declares each endpoint with its
+instance's `defineApi`, gathers them into named groups with `defineApiGroup`,
+and registers every group in one `registerApiGroups()` call. An endpoint's
+guards decide its mode, its name is `group.action`, a call goes to
+`{apiPath}/{group}/{action}`, and every caller reaches it through its group:
+`caller.orders.place(input)`.
+
+### Changed (breaking)
+
+- **`addApi` and `addSessionApi` are replaced by `defineApi`,
+  `defineApiGroup` and `registerApiGroups`.** `defineApi(options, handler)`
+  takes the options and the handler `addApi` took, and registers nothing by
+  itself; `defineApiGroup(name, { action: declaration })` gathers a group
+  (`defineApiGroup(name, partA, partB)` for one declared across files, an
+  action two parts declare being refused); `registerApiGroups(...groups)`
+  registers them and returns the instance typed with their contract, one flat
+  mapped type. The three builders are arrow properties, so an app hands them
+  out with `export const { defineApi, defineApiGroup, lazyApiGroup } =
+  lambderApp;`.
+  - To move: turn each chain of `addApi`/`addSessionApi` calls into a group of
+    `defineApi` declarations and register the groups in one call. Handler
+    bodies do not change.
+- **An endpoint's mode is its guards'.** An endpoint declaring a guard that
+  needs a session (`session: true`) is a session endpoint: its session is read
+  first, a call without one is answered `sessionExpired`, and its handler's
+  `ctx.session` is typed present. Every other endpoint is public. A
+  per-session rate limit on an endpoint none of whose guards needs a session,
+  and a session guard on an instance created without the `session` option,
+  are compile errors and registration errors.
+  - To move: give an endpoint that was an `addSessionApi` and declares no
+    session guard one: a no-op `lambderGuard({ session: true, handler: () => {} })`
+    where the session is its whole authorization.
+- **`requireSessionApiGuards` and `requirePublicApiGuards` are replaced by
+  `requireApiGuards`**, which makes `guards` a required field of every
+  endpoint.
+- **An endpoint is named `group.action`**, both identifiers (a letter, then
+  letters, digits or underscores). A group may not take the name of a
+  caller's public member or one a runtime asks of any object
+  (`LAMBDER_RESERVED_GROUP_NAMES`), nor an action one a function or any
+  object answers for (`then`, `call`, `toString`, `valueOf`:
+  `LAMBDER_RESERVED_ACTION_NAMES`), so converting a group to a string calls
+  no endpoint. The callers keep their state in
+  `#private` fields, so a group may take any name their public members leave
+  free (`transport`, `client`, `headers`).
+- **A call is `POST {apiPath}/{group}/{action}`**, the envelope in the body
+  and no `apiName` in it, so a gateway, a CDN and a log can meter, limit and
+  read calls per endpoint. `buildTransportEnvelope` writes no `apiName`, and
+  `readApiEnvelope(post, info, apiName)` takes the name from the path. A JSON
+  POST to `apiPath` itself naming an endpoint in its body is a page built
+  before endpoints had paths, and is answered `versionExpired`, which reloads
+  it.
+  - To move: an API Gateway route or a CloudFront behavior that matches
+    `apiPath` exactly (`POST /api`) now misses every call; widen it to what
+    is under it (`/api/*`, `ANY /api/{proxy+}`). A cookie an API handler sets
+    with a raw `Set-Cookie` header and no `Path` now defaults to the call's
+    directory (`/api/orders`) rather than `/`, in a browser as in the cookie
+    jar; `ctx.setCookie` and the session cookies always write `Path=/`.
+- **A request under `apiPath` that nothing matched is the API's**: a GET to a
+  call path, or a path of another depth, is answered as an unknown API rather
+  than by the public files, the shell or the route fallback. A root `apiPath`
+  shares every path with the site, so there only `apiPath` itself and the
+  calls are.
+- **The instance takes one type parameter**, `Lambder<TApp, TContract>`,
+  where `TApp` is `LambderAppTypes` (the session data, policies, guards,
+  idempotency, the guard requirement, sessions and the refusal vocabulary),
+  in place of ten positional generics. It is readable as the type-only
+  `AppTypes` property beside `ApiContract`.
+- **`use(plugin)` registers routes, hooks and actions**, and hands back the
+  same instance: endpoints are registered as groups, so a plugin adds nothing
+  to the contract.
+- **A `registerApiGroups()` call's groups take their place in the first-match
+  chain where the call stands**, as each `addApi` did: a route registered
+  before them sees their calls first, one registered after them never does.
+  The beforeRender hooks run before a lazy group loads, and a call to an
+  action its group does not have is answered as an unmatched API call, the
+  fallback hooks first.
+- **`apiOptionEntries()` is asynchronous**, as `apiSignatures()` and
+  `apiSignatureEntries()` are: all three load lazy groups first.
+- **The mock's `publicApi` and `sessionApi` are replaced by `api`, and
+  `sessionNotMocked` by `notMocked`.** An entry's mode is the `apiOptions`
+  table's when the mock was given it, and otherwise the server's rule applied
+  to the guards the entry restates. `LambderMockPublicNames` and
+  `LambderMockSessionNames` are removed. Every session endpoint must name at
+  least one mock guard declared `session: true`, a compile error at the
+  `guards` option otherwise (`LambderMockSessionGuardsCheck`), and a session
+  endpoint left unmocked on a mock without the table restates its guards,
+  `notMocked(name, { reason, guards })`, so a signed-out call answers
+  `sessionExpired` as the server does. `lambderMockInvokeTransport(mockApp,
+  { apiPath })` answers what the callee's server reads as a call, a JSON POST
+  to a call path under `apiPath` (default `"/api"`), and 404s anything else.
+- **`LambderMergeContract` is removed**, and `LambderAllowedGuardNames`,
+  `LambderParamlessGuardNames`, `LambderGuardsOption`,
+  `LambderAllowedPolicyNames` and `LambderRateLimitOption` lose their second
+  type parameter: every guard and every policy with a `per` may be declared
+  on any endpoint, a session guard making it a session one.
+
+### Added
+
+- **Every caller reaches an endpoint through its group.**
+  `caller.orders.place(input)` is `caller.api("orders.place", input)`, and
+  `caller.orders.place.outcome(input)` its `apiOutcome`, on `LambderCaller`,
+  `LambderInvokeCaller` and the test visitor alike. The groups are read off
+  the contract's type, so a client that imports its contract as a type ships
+  no endpoint list. A name that is not `group.action` is refused before it is
+  sent.
+- **Lazy groups.** `lazyApiGroup(name, () => import(...).then((m) => m.group))`
+  registers a group loaded on the first call to one of its endpoints, so a
+  cold start parses none of it until then; `loadApiGroups()` loads every one,
+  for a build step or a boot check. A hook that answers a call spares it the
+  import; one that throws a refusal, or charges a per-API budget, loads the
+  group, so the refusal is checked and the budget counted against the
+  endpoint called, as for an eager group. A load that fails is forgotten, and
+  the next call tries again.
+- **Compile-time registration checks**: a group typed `any`, a lazy group
+  loading one, or a group whose endpoints are (its endpoints would be `any` to
+  every client), and a group name given twice, are refused where
+  `registerApiGroups()` is written, and a group registration is atomic:
+  refused anywhere, it leaves the instance as it was. A lazy group written
+  where a list of groups is expected (a `satisfies`, an annotated array)
+  keeps its loaded group's type, rather than taking the expected `any`.
+- **`beforeCall` on `LambderInvokeCaller`**: a check run before every call,
+  `api()`, `apiOutcome()`, a group's call and `request()` alike, before
+  anything is built or sent. What it throws is thrown to the caller, from
+  `apiOutcome()` too, and `onFailure` is not told, since nothing was sent. It
+  is where a rule the calling code must keep goes, such as never calling out
+  while a database transaction is open (`LambderInvokeCallCheck`).
+- **What registering endpoints costs the compiler grows linearly**: each
+  declaration is typed on its own, and eight hundred endpoints cost under four
+  times what two hundred do, which the type-cost suite holds.
+- Exports: `apiCallPath`, `apiNameOfCallPath`, `splitApiName`, `isGroupName`,
+  `isActionName`, `LAMBDER_API_NAME_SEGMENT`, `LAMBDER_CALLER_MEMBER_NAMES`,
+  `LAMBDER_RESERVED_GROUP_NAMES`, `LAMBDER_RESERVED_ACTION_NAMES`, and the
+  types of declarations, groups and group calls (see
+  [Exports](./docs/exports.md#endpoints-declarations-groups-and-names)).
+
+## [11.1.1] - 2026-09-30
+
+A minor for an app whose shell files sit behind a shared cache: a file whose
+name does not change when its bytes do is revalidated rather than kept.
+
+### Changed
+
+- **`servePublicFiles` answers a file its immutable rule does not match with
+  `Cache-Control: no-cache`**, where it answered `public, max-age=3600`. A
+  service worker, a web manifest or a favicon keeps its name across a deploy,
+  so a CDN or proxy honouring the hour served the old copy to everyone for up
+  to an hour afterwards, and an app behind one had to purge it on every
+  deploy. Every GET or HEAD 200 already carries an ETag, so a revalidation of
+  an unchanged file is a 304 with no body. Content-hashed build output keeps
+  `immutableCacheControl`, and an app that wants the old behaviour passes
+  `cacheControl: "public, max-age=3600"`.
+
 ## [11.0.1] - 2026-09-29
 
 A major for an app with many APIs: what one API costs the type checker no

package/README.md

@@ -10,25 +10,30 @@ per-handler boilerplate.
 import { initLambder, LambderLocalFileSource, LambderDdbSessionStore } from "lambder";
 import { z } from "zod";
 
-const lambder = initLambder<SessionData>().create({
+const app = initLambder<SessionData>().create({
     apiPath: "/api",
     files: new LambderLocalFileSource({ root: "./public" }),
     session: { store: new LambderDdbSessionStore({ tableName: "app-session", region: "us-east-1" }), sessionSalt: process.env.SESSION_SALT! },
-}).addApi("getCompany", {
-    input: z.object({ slug: z.string() }),
-    output: z.object({ id: z.string(), name: z.string() }),
-}, async ({ apiPayload }) => await loadCompany(apiPayload.slug));
+});
 
+const companyApis = app.defineApiGroup("companies", {
+    get: app.defineApi({
+        input: z.object({ slug: z.string() }),
+        output: z.object({ id: z.string(), name: z.string() }),
+    }, async ({ apiPayload }) => await loadCompany(apiPayload.slug)),
+});
+
+export const lambder = app.registerApiGroups(companyApis);
 export type ApiContractType = typeof lambder.ApiContract;
 export const handler = lambder.getHandler();
 ```
 
-A handler returns its output, which is parsed through the output schema before
-it is sent, and says no by throwing a refusal: `ctx.refuse()`, typed to the
-codes the API declares, or `refuse()` from anywhere. Registration chains onto the
-creation call: every `addApi` returns an instance carrying the contract so
-far, so the whole backend is one declaration and `lambder.ApiContract` is the
-accumulated type.
+An endpoint is a value: declared with `defineApi`, gathered into a named
+group, registered with its groups in one call, and called at
+`/api/companies/get`. A handler returns its output, which is parsed through
+the output schema before it is sent, and says no by throwing a refusal:
+`ctx.refuse()`, typed to the codes the API declares, or `refuse()` from
+anywhere. Its guards say who may call it, and so whether it needs a session.
 
 The frontend imports that contract type and gets autocomplete, typed payloads
 and typed results with no hand-written client:
@@ -38,7 +43,7 @@ import { LambderCaller } from "lambder/client";
 import type { ApiContractType } from "./backend/handler";
 
 const caller = new LambderCaller<ApiContractType>({ apiPath: "/api" });
-const company = await caller.api("getCompany", { slug: "acme" });
+const company = await caller.companies.get({ slug: "acme" });
 ```
 
 ## Features
@@ -166,7 +171,7 @@ guide that matches what you are building. The full index lives in
 | [Getting started](./docs/getting-started.md) | The three-step path from a first API to a typed frontend call |
 | [Configuration](./docs/configuration.md) | Every `initLambder().create({...})` option, in one reference |
 | [Routing and actions](./docs/routing.md) | Routes, matchers, hooks, fallbacks, crash reporting, and non-HTTP invocations |
-| [APIs and refusals](./docs/apis.md) | `addApi`/`addSessionApi`, the inferred contract, `refuse()` and `LambderApiRefusal`, the signature file |
+| [APIs and refusals](./docs/apis.md) | `defineApi`, groups and lazy groups, the mode the guards decide, the inferred contract, `refuse()` and `LambderApiRefusal`, the signature file |
 | [Responses](./docs/responses.md) | The render context and its response tools (headers, cookies, log entries), the response builder routes and hooks use, compression, ETag and the size cap |
 | [Sessions](./docs/sessions.md) | Sessions over a store, cookie scope, secrets at rest, `dataRefresh`, the controller API |
 | [API policies](./docs/api-policies.md) | Declarative rate limits, guards and idempotency, and mandatory authorization declarations |

package/dist/api/LambderApiDeclarations.d.ts

@@ -0,0 +1,194 @@
+import type { z } from "zod";
+import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
+import type { LambderApiMode, LambderGuardNamesIn } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue, LambderRefusalsOptionValue } from "../shared/wire/LambderApiOptionValues.js";
+import type { LambderApiRateLimitPolicyConfig, LambderPolicyPerOf } from "./LambderApiRateLimits.js";
+import type { LambderRefusalVocabulary } from "./LambderApiRefusals.js";
+import { type LambderReservedActionName, type LambderReservedGroupName } from "../shared/wire/LambderApiNames.js";
+/**
+ * What an instance's declarations are typed against, fixed at create(): the
+ * session data, the rate-limit policies, the guards (as LambderGuardMetaMap
+ * records them), whether idempotency is configured, whether every endpoint
+ * must declare a guard, whether sessions are configured, and the refusal
+ * vocabulary with whether every refusal must name a code.
+ */
+export type LambderAppTypes = {
+    session: unknown;
+    policies: Record<string, LambderApiRateLimitPolicyConfig>;
+    guards: Record<string, any>;
+    idempotency: boolean;
+    guardsRequired: boolean;
+    sessions: boolean;
+    refusals: LambderRefusalVocabulary;
+    refusalCodesRequired: boolean;
+};
+/** The types of an instance built without create(): no policies, guards or vocabulary, sessions allowed. */
+export type LambderPlainAppTypes<TSession = any> = {
+    session: TSession;
+    policies: {};
+    guards: {};
+    idempotency: false;
+    guardsRequired: false;
+    sessions: true;
+    refusals: {};
+    refusalCodesRequired: false;
+};
+/** The guards among the names an endpoint declares that need a session (`session: true`). */
+export type LambderSessionGuardNamesIn<TGuards, TGuardsOpt> = {
+    [K in LambderGuardNamesIn<TGuardsOpt> & keyof TGuards]: TGuards[K] extends {
+        session: true;
+    } ? K : never;
+}[LambderGuardNamesIn<TGuardsOpt> & keyof TGuards];
+/**
+ * An endpoint's mode, from the guards it declares: "session" when any of
+ * them needs a session, "public" otherwise. The guard is the one place the
+ * endpoint says who may call it, and a session is part of that answer, so
+ * nothing else states the mode and nothing can disagree with it.
+ */
+export type LambderApiModeOf<TGuards, TGuardsOpt> = [
+    LambderSessionGuardNamesIn<TGuards, TGuardsOpt>
+] extends [never] ? "public" : "session";
+/** The per-session policies among the names an endpoint's rateLimit option declares. */
+type LambderSessionPolicyNamesIn<TPolicies, TRateOpt> = {
+    [K in LambderGuardNamesIn<TRateOpt> & keyof TPolicies]: [LambderPolicyPerOf<TPolicies[K]>] extends ["session"] ? K : never;
+}[LambderGuardNamesIn<TRateOpt> & keyof TPolicies];
+/**
+ * A public endpoint's per-session rate limits, refused on the option: a
+ * public call carries no session to count against. The property name is the
+ * message and its value the policies at fault.
+ */
+export type LambderPublicSessionPolicyCheck<TMode extends LambderApiMode, TPolicies, TRateOpt> = TMode extends "session" ? unknown : [LambderSessionPolicyNamesIn<TPolicies, TRateOpt>] extends [never] ? unknown : {
+    rateLimit: {
+        readonly "lambder: these rate limits count per session, and none of this API's guards needs a session": LambderSessionPolicyNamesIn<TPolicies, TRateOpt>;
+    };
+};
+/** What a session endpoint needs of its instance: sessions configured at create(). */
+type LambderSessionsConfigured = {
+    readonly "lambder: a guard of this API needs a session, and sessions are not configured on this instance. Pass the session option to create().": never;
+};
+/** A session endpoint on an instance without sessions, refused where it is declared. */
+export type LambderSessionModeCheck<TMode extends LambderApiMode, TSessions extends boolean> = TMode extends "session" ? (TSessions extends true ? unknown : LambderSessionsConfigured) : unknown;
+/** One endpoint's options as registration reads them. */
+export type LambderApiDeclarationOptions = {
+    input: z.ZodType;
+    output: z.ZodType;
+    guards?: LambderGuardsOptionValue;
+    rateLimit?: LambderRateLimitOptionValue;
+    idempotency?: LambderApiIdempotencyOption;
+    refusals?: LambderRefusalsOptionValue;
+    compress?: boolean | "auto";
+};
+/** The key the contract entry of a declaration is typed under. It exists only in types: nothing reads or writes it. */
+declare const LAMBDER_CONTRACT_ENTRY: unique symbol;
+/**
+ * One endpoint, declared: its options and its handler, and in its type the
+ * contract entry a client calls it by. Built by an instance's defineApi(),
+ * registered by being put in a group.
+ */
+export type LambderApiDeclaration<TEntry = unknown> = {
+    readonly kind: "lambderApi";
+    readonly options: LambderApiDeclarationOptions;
+    readonly handler: (ctx: never) => MaybePromise<unknown>;
+    readonly [LAMBDER_CONTRACT_ENTRY]: TEntry;
+};
+/** A group's endpoints by action name. */
+export type LambderApiDeclarations = Record<string, LambderApiDeclaration<any>>;
+/** A group of endpoints: `name.action` for each of its actions. Built by defineApiGroup(). */
+export type LambderApiGroup<TName extends string = string, TApis extends LambderApiDeclarations = LambderApiDeclarations> = {
+    readonly kind: "lambderApiGroup";
+    readonly name: TName;
+    readonly apis: TApis;
+};
+/**
+ * A group loaded on the first call to one of its endpoints: its name, and
+ * how to load it. Built by lazyApiGroup(). What a cold start parses then
+ * leaves out every group no request has called yet.
+ */
+export type LambderLazyApiGroup<TName extends string = string, TGroup extends LambderApiGroup<TName, any> = LambderApiGroup<TName, any>> = {
+    readonly kind: "lambderLazyApiGroup";
+    readonly name: TName;
+    readonly load: () => Promise<TGroup>;
+};
+/** Either kind of group registerApiGroups() takes. */
+export type LambderRegistrableApiGroup = LambderApiGroup<string, any> | LambderLazyApiGroup<string, any>;
+/** A declaration's contract entry. */
+export type LambderEntryOf<TDeclaration> = TDeclaration extends {
+    readonly [LAMBDER_CONTRACT_ENTRY]: infer TEntry;
+} ? TEntry : never;
+type LambderLoadedGroupOf<TGroup> = TGroup extends LambderLazyApiGroup<string, infer TLoaded> ? TLoaded : TGroup;
+/**
+ * One group's part of the contract: `group.action` for each action, its
+ * declaration's entry. Distributed over a union of groups (the `TGroup
+ * extends unknown`), so each group is read on its own: read as one union,
+ * the actions would be only those every group shares.
+ */
+type LambderGroupContract<TGroup> = TGroup extends unknown ? (LambderLoadedGroupOf<TGroup> extends LambderApiGroup<infer TName, infer TApis> ? {
+    [TAction in keyof TApis & string as `${TName}.${TAction}`]: LambderEntryOf<TApis[TAction]>;
+} : never) : never;
+type LambderUnionToIntersection<TUnion> = (TUnion extends unknown ? (value: TUnion) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+/** The contract of every group registered together, as one flat object type keyed by endpoint name. */
+export type LambderContractOfGroups<TGroups extends readonly unknown[]> = LambderUnionToIntersection<LambderGroupContract<TGroups[number]>> extends infer TMerged ? {
+    [TName in keyof TMerged]: TMerged[TName];
+} : never;
+/**
+ * Whether a group, the group a lazy one loads, or that group's endpoints is
+ * typed any. A part typed any, merged with the rest, comes out as an index
+ * signature rather than as any, and no group declared action by action has
+ * one, so that counts too.
+ */
+type LambderGroupTypedAny<TGroup> = 0 extends 1 & TGroup ? true : 0 extends 1 & LambderLoadedGroupOf<TGroup> ? true : LambderLoadedGroupOf<TGroup> extends {
+    readonly apis: infer TApis;
+} ? (0 extends 1 & TApis ? true : string extends keyof TApis ? true : false) : false;
+/** The group names one registerApiGroups() call names twice. */
+type LambderRepeatedGroupNames<TGroups extends readonly unknown[], TSeen = never> = TGroups extends readonly [infer THead, ...infer TRest] ? (THead extends {
+    name: infer TName;
+} ? ([TName] extends [TSeen] ? TName : never) | LambderRepeatedGroupNames<TRest, TSeen | TName> : never) : never;
+/**
+ * What registerApiGroups() asks of its receiver: the instance itself, unless
+ * a group, what a lazy group loads or a group's endpoints is typed `any` (a
+ * module whose types were lost would otherwise make its endpoints `any` to
+ * every client) or a group name is given twice (two
+ * groups of one name would be one namespace with two owners). Then it asks
+ * for an object no instance is, whose property name is the message, so the
+ * call is refused where it is written.
+ */
+export type LambderRegisteredGroupsCheck<TGroups extends readonly unknown[], TSelf> = true extends {
+    [TIndex in keyof TGroups]: LambderGroupTypedAny<TGroups[TIndex]>;
+}[number] ? {
+    readonly "lambder: a group given to registerApiGroups, what a lazy group loads, or a group's endpoints is typed any, which would make its part of the contract any. Build it with defineApiGroup() and let its type through.": never;
+} : [LambderRepeatedGroupNames<TGroups>] extends [never] ? TSelf : {
+    readonly "lambder: these group names are registered twice": LambderRepeatedGroupNames<TGroups>;
+};
+/** A group's name held to the rule a caller's properties need. */
+export type LambderGroupNameCheck<TName extends string> = TName extends LambderReservedGroupName ? {
+    readonly "lambder: a caller already has a member of this name, so no group may take it": TName;
+} : unknown;
+/** The actions more than one of a group's parts declare. */
+type LambderRepeatedActions<TParts extends readonly unknown[], TSeen = never> = TParts extends readonly [infer THead, ...infer TRest] ? (Extract<keyof THead, TSeen> | LambderRepeatedActions<TRest, TSeen | keyof THead>) : never;
+/** A group's parts held to declaring each action once: a part would otherwise replace another's endpoint of the same name. */
+export type LambderGroupPartsCheck<TParts extends readonly unknown[]> = [
+    LambderRepeatedActions<TParts>
+] extends [never] ? unknown : {
+    readonly "lambder: these actions are declared by more than one part of the group": LambderRepeatedActions<TParts>;
+};
+/** One group's endpoints, from the parts it was declared in. */
+export type LambderMergedParts<TParts extends readonly unknown[]> = LambderUnionToIntersection<TParts[number]> extends infer TMerged ? {
+    [TAction in keyof TMerged]: TMerged[TAction];
+} : never;
+/** A group's action names held to the rule the functions a caller hands out need. */
+export type LambderActionNamesCheck<TApis> = [
+    Extract<keyof TApis, LambderReservedActionName>
+] extends [never] ? unknown : {
+    readonly "lambder: a function already has a member of these names, so no action may take them": Extract<keyof TApis, LambderReservedActionName>;
+};
+/**
+ * Builds a group from its parts, refusing a name no caller could carry, an
+ * action two parts declare, and a value that is not an endpoint. A group is
+ * usually one part; one declared across files gives each file's part.
+ */
+export declare const buildApiGroup: <TName extends string, TApis extends LambderApiDeclarations>(name: TName, parts: readonly LambderApiDeclarations[]) => LambderApiGroup<TName, TApis>;
+/** Builds a lazy group; the name is checked here, the group it loads when it loads. */
+export declare const buildLazyApiGroup: <TName extends string, TGroup extends LambderApiGroup<TName, any>>(name: TName, load: () => Promise<TGroup>) => LambderLazyApiGroup<TName, TGroup>;
+/** Whether a value is either kind of group registerApiGroups() takes. */
+export declare const isRegistrableApiGroup: (value: unknown) => value is LambderRegistrableApiGroup;
+export {};

package/dist/api/LambderApiDeclarations.js

@@ -0,0 +1,52 @@
+import { isActionName, isGroupName, LAMBDER_API_NAME_SEGMENT } from "../shared/wire/LambderApiNames.js";
+const describeName = (name) => typeof name === "string" ? `"${name}"` : String(name);
+/**
+ * Builds a group from its parts, refusing a name no caller could carry, an
+ * action two parts declare, and a value that is not an endpoint. A group is
+ * usually one part; one declared across files gives each file's part.
+ */
+export const buildApiGroup = (name, parts) => {
+    if (typeof name !== "string" || !isGroupName(name)) {
+        throw new Error(`Lambder: ${describeName(name)} cannot name a group. A group is a letter then letters, digits or underscores, ` +
+            `and not a name a caller already answers for (api, apiOutcome, then, ...).`);
+    }
+    const apis = {};
+    for (const part of parts) {
+        if (part === null || typeof part !== "object") {
+            throw new Error(`Lambder: a part of group "${name}" is not an object of endpoints by action name.`);
+        }
+        for (const [action, declaration] of Object.entries(part)) {
+            if (Object.prototype.hasOwnProperty.call(apis, action)) {
+                throw new Error(`Lambder: "${name}.${action}" is declared by two parts of group "${name}". Each action is declared once.`);
+            }
+            apis[action] = declaration;
+        }
+    }
+    if (Object.keys(apis).length === 0) {
+        throw new Error(`Lambder: group "${name}" declares no endpoints. A group is its endpoints by action name: defineApiGroup("${name}", { action: defineApi(...) }).`);
+    }
+    for (const [action, declaration] of Object.entries(apis)) {
+        if (!isActionName(action)) {
+            throw new Error(`Lambder: "${name}.${action}" cannot name an endpoint. An action is a letter then letters, digits or underscores, ` +
+                `and not a name a function already answers for (then, outcome, call, ...).`);
+        }
+        if (declaration?.kind !== "lambderApi") {
+            throw new Error(`Lambder: "${name}.${action}" is not an endpoint declaration. Declare it with the instance's defineApi().`);
+        }
+    }
+    return { kind: "lambderApiGroup", name, apis: apis };
+};
+/** Builds a lazy group; the name is checked here, the group it loads when it loads. */
+export const buildLazyApiGroup = (name, load) => {
+    if (typeof name !== "string" || !isGroupName(name)) {
+        throw new Error(`Lambder: ${describeName(name)} cannot name a group. A group is a letter then letters, digits or underscores, and not a name a caller already answers for.`);
+    }
+    if (typeof load !== "function")
+        throw new Error(`Lambder: lazy group "${name}" has no loader. Pass a function that imports the group: () => import("./orders.js").then((m) => m.orderApis).`);
+    return { kind: "lambderLazyApiGroup", name, load };
+};
+/** Whether a value is either kind of group registerApiGroups() takes. */
+export const isRegistrableApiGroup = (value) => {
+    const kind = value?.kind;
+    return (kind === "lambderApiGroup" || kind === "lambderLazyApiGroup") && typeof value.name === "string" && LAMBDER_API_NAME_SEGMENT.test(value.name);
+};

package/dist/api/LambderApiDefinition.d.ts

@@ -4,7 +4,7 @@ import type { LambderApiMode } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "../shared/wire/LambderApiOptionValues.js";
 /**
  * One endpoint's declaration as the pipeline runs it: what the server's
- * addApi/addSessionApi options carry, minus the handler, in a shape the mock
+ * defineApi options carry, minus the handler, in a shape the mock
  * runtime can restate from a type-only contract. The schemas are optional
  * because the mock has none; when input is present, validation runs and the
  * handler sees the parsed payload. Output is part of the endpoint's

package/dist/api/LambderApiGuards.d.ts

@@ -72,9 +72,11 @@ export type LambderGuardRefusals<TRefusals extends readonly string[] = readonly
  *
  * Orthogonally, a guard may also:
  *
- * - declare `session: true`: the guard needs ctx.session, so it is only
- *   declarable on addSessionApi (compile error and startup assert on public
- *   APIs) and its handler receives the session-typed context.
+ * - declare `session: true`: the guard needs ctx.session, so it makes every
+ *   endpoint declaring it a session endpoint (the session is read before the
+ *   guards run, a call without one is answered sessionExpired, and the
+ *   endpoint's handler receives the session-typed context), and it receives
+ *   the session-typed context itself.
  * - take a PARAMETER: annotate a 3rd handler argument
  *   (`(ctx, payload, param: YourType) => ...`) and APIs pass the value in
  *   their declaration: `guards: { yourGuard: paramValue }`. The value is
@@ -272,19 +274,16 @@ export type LambderGuardMetaMap<TGuards> = {
     [K in keyof TGuards]: LambderGuardMeta<TGuards[K]>;
 };
 /**
- * Guard names an API may declare: every guard the instance holds, session
- * guards only on session APIs. Whether the API's input carries the fields an
- * apiInput guard reads is asked of the names it declared, once that input is
- * known, by LambderGuardNamesInputLacks.
+ * Guard names an API may declare: every guard the instance holds, a session
+ * guard included, which makes the API a session one (LambderApiModeOf).
+ * Whether the API's input carries the fields an apiInput guard reads is
+ * asked of the names it declared, once that input is known, by
+ * LambderGuardNamesInputLacks.
  */
-export type LambderAllowedGuardNames<TGuards, TIncludeSession extends boolean = true> = {
-    [K in keyof TGuards]: TGuards[K] extends {
-        session: true;
-    } ? (TIncludeSession extends true ? K : never) : K;
-}[keyof TGuards] & string;
+export type LambderAllowedGuardNames<TGuards> = keyof TGuards & string;
 /**
  * The apiInput guards among `TNames` whose fields the API's payload does not
- * carry. addApi and addSessionApi ask this once the API's input is known, of
+ * carry. defineApi asks this once the API's input is known, of
  * the names its guards option holds; see LambderPayloadSliceCheck.
  *
  * The payload is compared whole, not member by member: a bare `TPayload
@@ -298,14 +297,14 @@ export type LambderGuardNamesInputLacks<TGuards, TNames, TPayload> = {
     } ? ([TPayload] extends [R] ? never : K) : never;
 }[TNames & keyof TGuards] & string;
 /** The allowed guard names whose handler takes no param (usable in the string/array forms). */
-export type LambderParamlessGuardNames<TGuards, TIncludeSession extends boolean> = {
-    [K in LambderAllowedGuardNames<TGuards, TIncludeSession> & keyof TGuards]: TGuards[K] extends {
+export type LambderParamlessGuardNames<TGuards> = {
+    [K in LambderAllowedGuardNames<TGuards> & keyof TGuards]: TGuards[K] extends {
         param: undefined;
     } ? K & string : never;
-}[LambderAllowedGuardNames<TGuards, TIncludeSession> & keyof TGuards];
+}[LambderAllowedGuardNames<TGuards> & keyof TGuards];
 /** The map form's full shape: every declarable guard name, each carrying its own param type. */
-type LambderGuardsMap<TGuards, TIncludeSession extends boolean> = {
-    readonly [K in LambderAllowedGuardNames<TGuards, TIncludeSession> & keyof TGuards]?: TGuards[K] extends {
+type LambderGuardsMap<TGuards> = {
+    readonly [K in LambderAllowedGuardNames<TGuards> & keyof TGuards]?: TGuards[K] extends {
         param: undefined;
     } ? true : TGuards[K] extends {
         param: infer P;
@@ -324,10 +323,10 @@ type LambderGuardsMap<TGuards, TIncludeSession extends boolean> = {
  * compiler builds it once per instance rather than once per API; see
  * LambderPayloadSliceCheck for why, and for where the input is asked.
  */
-export type LambderGuardsOption<TGuards, TIncludeSession extends boolean> = LambderParamlessGuardNames<TGuards, TIncludeSession> | readonly [
-    LambderParamlessGuardNames<TGuards, TIncludeSession>,
-    ...LambderParamlessGuardNames<TGuards, TIncludeSession>[]
-] | LambderNonEmptyOptionMap<LambderGuardsMap<TGuards, TIncludeSession>>;
+export type LambderGuardsOption<TGuards> = LambderParamlessGuardNames<TGuards> | readonly [
+    LambderParamlessGuardNames<TGuards>,
+    ...LambderParamlessGuardNames<TGuards>[]
+] | LambderNonEmptyOptionMap<LambderGuardsMap<TGuards>>;
 /**
  * The typed ctx.guardData an API's handler sees: declared guards that return
  * a value, keyed by name. Check-only (void) guards never appear.

package/dist/api/LambderApiGuards.js

@@ -101,7 +101,7 @@ export class LambderApiGuardsEngine {
                 throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Declare it in the guards option at creation.`);
             }
             if (guardDef.session && mode !== "session") {
-                throw new Error(`Lambder: API "${apiName}" uses guard "${name}" (session: true), which requires addSessionApi.`);
+                throw new Error(`Lambder: API "${apiName}" uses guard "${name}" (session: true) but is registered as public. An endpoint declaring a session guard is a session endpoint.`);
             }
         }
     }

package/dist/api/LambderApiRateLimits.d.ts

@@ -116,7 +116,7 @@ export type LambderApiRateLimitPolicyConfig<TCtx = any> = LambderRateLimitPolicy
 export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig<any>>> = {
     /** Your limiter instance (LambderDdbRateLimiter, LambderMemoryRateLimiter, or your own); its table and keyPrefix apply as configured on it. */
     limiter: LambderRateLimiter;
-    /** Named policies referenced (typed) from addApi/addSessionApi. */
+    /** Named policies referenced (typed) from defineApi. */
     policies: TPolicies;
     /**
      * Let the request through when the limiter itself fails (the table is
@@ -144,23 +144,23 @@ export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderA
  * without one, and a union holding undefined for a policy typed as the
  * general LambderApiRateLimitPolicyConfig, where only registration can tell.
  */
-type LambderPolicyPerOf<TPolicy> = "per" extends keyof TPolicy ? TPolicy["per" & keyof TPolicy] : undefined;
+export type LambderPolicyPerOf<TPolicy> = "per" extends keyof TPolicy ? TPolicy["per" & keyof TPolicy] : undefined;
 /**
- * Policy names an API may reference: session-keyed policies only on session
- * APIs, and never a policy without `per`, whose key only the code that
- * charges it knows. A policy whose type does not settle its `per` is allowed
- * here and checked at registration. Whether the API's input carries the
- * fields an apiInput-keyed policy reads is asked of the names it declared,
- * once that input is known, by LambderPolicyNamesInputLacks.
+ * Policy names an API may reference: never a policy without `per`, whose key
+ * only the code that charges it knows. A policy whose type does not settle
+ * its `per` is allowed here and checked at registration. A session-keyed
+ * policy is allowed here too, and refused of an API none of whose guards
+ * needs a session by LambderPublicSessionPolicyCheck, once its guards are
+ * known. Whether the API's input carries the fields an apiInput-keyed policy
+ * reads is asked of the names it declared, once that input is known, by
+ * LambderPolicyNamesInputLacks.
  */
-export type LambderAllowedPolicyNames<TPolicies, TIncludeSession extends boolean> = {
-    [K in keyof TPolicies]: [
-        LambderPolicyPerOf<TPolicies[K]>
-    ] extends [undefined] ? never : [LambderPolicyPerOf<TPolicies[K]>] extends ["session"] ? (TIncludeSession extends true ? K : never) : K;
+export type LambderAllowedPolicyNames<TPolicies> = {
+    [K in keyof TPolicies]: [LambderPolicyPerOf<TPolicies[K]>] extends [undefined] ? never : K;
 }[keyof TPolicies] & string;
 /**
  * The apiInput-keyed policies among `TNames` whose key fields the API's
- * payload does not carry. addApi and addSessionApi ask this once the API's
+ * payload does not carry. defineApi asks this once the API's
  * input is known, of the names its rateLimit option holds; see
  * LambderPayloadSliceCheck.
  *
@@ -235,8 +235,8 @@ type LambderRateLimitOverrideFor<TPolicy> = TPolicy extends {
     budget: "perPolicy";
 } ? Pick<LambderRateLimitOverride, "refusal"> : LambderRateLimitOverride;
 /** The map form's full shape: every referable policy name, each carrying its own override. */
-type LambderRateLimitMap<TPolicies, TIncludeSession extends boolean> = {
-    readonly [K in LambderAllowedPolicyNames<TPolicies, TIncludeSession> & keyof TPolicies]?: true | LambderRateLimitOverrideFor<TPolicies[K]>;
+type LambderRateLimitMap<TPolicies> = {
+    readonly [K in LambderAllowedPolicyNames<TPolicies> & keyof TPolicies]?: true | LambderRateLimitOverrideFor<TPolicies[K]>;
 };
 /**
  * The per-API `rateLimit` option: one policy name, a non-empty ordered list
@@ -251,10 +251,10 @@ type LambderRateLimitMap<TPolicies, TIncludeSession extends boolean> = {
  * It depends on the instance alone, never on the API's input, as
  * LambderGuardsOption does; see LambderPayloadSliceCheck.
  */
-export type LambderRateLimitOption<TPolicies, TIncludeSession extends boolean> = LambderAllowedPolicyNames<TPolicies, TIncludeSession> | readonly [
-    LambderAllowedPolicyNames<TPolicies, TIncludeSession>,
-    ...LambderAllowedPolicyNames<TPolicies, TIncludeSession>[]
-] | LambderNonEmptyOptionMap<LambderRateLimitMap<TPolicies, TIncludeSession>>;
+export type LambderRateLimitOption<TPolicies> = LambderAllowedPolicyNames<TPolicies> | readonly [
+    LambderAllowedPolicyNames<TPolicies>,
+    ...LambderAllowedPolicyNames<TPolicies>[]
+] | LambderNonEmptyOptionMap<LambderRateLimitMap<TPolicies>>;
 /**
  * When in a call a policy is checked.
  *