create-qpq-app 0.1.5

package/template/docusaurus/docs/config/webserver/open-api.md

@@ -0,0 +1,36 @@
+---
+title: defineOpenApi
+description: Point a service at an OpenAPI spec file describing its HTTP API.
+---
+
+# defineOpenApi
+
+Registers an **OpenAPI spec** for the service by pointing at a spec file on disk. This associates a machine-readable description of the service's HTTP API with the config.
+
+- **On AWS:** no infrastructure of its own — it records the spec path in the config. The generated spec is retrievable at runtime with [askGetOpenApiSpec](../../actions/webserver/open-api-spec/ask-get-open-api-spec.md).
+
+```typescript
+import { defineOpenApi } from 'quidproquo-webserver';
+
+export default [
+  defineOpenApi('./openapi.json'),
+];
+```
+
+## Signature
+
+```typescript
+function defineOpenApi(openApiSpecPath: string): OpenApiQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `openApiSpecPath` — `string` (required)
+
+Path to the OpenAPI spec file for the service. This value is also the setting's `uniqueKey`.
+
+## Related
+
+- [askGetOpenApiSpec](../../actions/webserver/open-api-spec/ask-get-open-api-spec.md) — read the OpenAPI spec from within a story.
+- [defineApi](./api.md) — the HTTP API the spec describes.
+- [defineRoute](./route.md) — the routes that make up the API surface.

package/template/docusaurus/docs/config/webserver/route.md

@@ -0,0 +1,109 @@
+---
+title: defineRoute
+description: Define a single HTTP route — map a method and path to a story runtime, with per-route CORS and auth options.
+---
+
+# defineRoute
+
+Defines an **HTTP route**: a mapping from an HTTP method and URL path to a **story runtime** that handles the request. Routes are served under the service's [API](./api.md). Each incoming request matching the method and path runs the referenced story, which returns the HTTP response.
+
+- **On AWS:** routes are not individual infrastructure. API Gateway proxies every request to the single API Lambda, which matches the request against all declared routes at runtime and dispatches to the matching story. See [defineApi](./api.md) for the deployed resources.
+
+```typescript
+import { defineRoute } from 'quidproquo-webserver';
+
+export default [
+  defineRoute('GET', '/users/{userId}', '/src/routes/users/getUser::getUser'),
+];
+```
+
+## Signature
+
+```typescript
+function defineRoute(
+  method: HTTPMethod,
+  path: string,
+  runtime: QpqFunctionRuntime,
+  options?: GenericRouteOptions<ApiKeyReference | string>,
+): RouteQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `method` — `HTTPMethod` (required)
+
+The HTTP method to match. `HTTPMethod` is one of `'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'PATCH'`.
+
+### `path` — `string` (required)
+
+The URL path to match, e.g. `'/users/{userId}'`. Path parameters are written with braces (`{userId}`) and are made available to the handling story via the HTTP event.
+
+### `runtime` — `QpqFunctionRuntime` (required)
+
+A reference to the story that handles the request. Usually written as a relative path string of the form `'/path/to/file::exportedFunctionName'` (for example `'/src/routes/users/getUser::getUser'`). The handler story receives the HTTP event and returns the HTTP response. This value is also the route's `uniqueKey`.
+
+### `options` — `GenericRouteOptions<ApiKeyReference | string>` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `allowedOrigins` | `(string \| ServiceAllowedOrigin)[]` | – | Browser origins allowed to call this route (CORS). Either literal origin strings or `ServiceAllowedOrigin` descriptors resolved to another qpq service's domain. Merged with any [default route options](./default-route-options.md). |
+| `routeAuthSettings` | `RouteAuthSettings` | – | How the route is authenticated/authorized. See below. |
+
+#### `RouteAuthSettings`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `userDirectoryName` | `string` | Name of the `defineUserDirectory` whose access tokens authenticate this route. The request's bearer token is decoded and validated against this directory. |
+| `scopes` | `string[]` | Scopes/roles the caller's token must carry to be authorized. |
+| `apiKeys` | `(ApiKeyReference \| string)[]` | API keys accepted for this route. A plain string is shorthand for `{ name }`; use an `ApiKeyReference` (`{ name, applicationName?, serviceName? }`) to reference a key declared in another application or service. |
+
+#### `ServiceAllowedOrigin`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `api` | `string` | The API subdomain name of the target service. |
+| `domain` | `string` | The domain the target service is hosted on. Defaults to this service's domain. |
+| `service` | `string` | The service name as seen in the subdomain. |
+| `protocol` | `'http' \| 'https'` | Protocol to use; defaults to `https`. |
+
+## Notes
+
+- Route options are **merged** with every [defineDefaultRouteOptions](./default-route-options.md) declared in the service: `allowedOrigins` are unioned and `routeAuthSettings` (user directory, scopes, api keys) are combined. Per-route settings and defaults add together rather than one replacing the other.
+- Auth decoding and validation of the incoming token is performed by the `askRouteAuthValidationDecode` action, driven by the service's auth system (see `defineAuthSystem`).
+
+## Examples
+
+```typescript
+import { defineRoute } from 'quidproquo-webserver';
+
+export default [
+  // Public read endpoint
+  defineRoute('GET', '/articles', '/src/routes/articles/list::listArticles'),
+
+  // Path parameter
+  defineRoute('GET', '/articles/{articleId}', '/src/routes/articles/get::getArticle'),
+
+  // Authenticated write, requires a user directory token with a scope
+  defineRoute('POST', '/articles', '/src/routes/articles/create::createArticle', {
+    routeAuthSettings: {
+      userDirectoryName: 'users',
+      scopes: ['articles:write'],
+    },
+  }),
+
+  // Protected by an API key
+  defineRoute('POST', '/webhooks/stripe', '/src/routes/webhooks/stripe::onStripeEvent', {
+    routeAuthSettings: {
+      apiKeys: ['stripe-webhook-key'],
+    },
+  }),
+];
+```
+
+## Related
+
+- [defineApi](./api.md) — the API the route is served under.
+- [defineDefaultRouteOptions](./default-route-options.md) — service-wide CORS/auth defaults merged into each route.
+- [defineServiceFunction](./service-function.md) — RPC-style handlers that are not exposed as HTTP routes.
+- [askRouteAuthValidationDecode](../../actions/webserver/route-auth-validation/ask-route-auth-validation-decode.md) — decodes and validates a route's auth token.
+- [defineVersionedRoute](../features/versioned-route.md) — wraps this to serve a route under a `/v1`, `/v2`, … version prefix.

package/template/docusaurus/docs/config/webserver/seed.md

@@ -0,0 +1,61 @@
+---
+title: defineSeed
+description: Register deploy-time seed stories that run once, on the first deploy, to populate a service with initial data.
+---
+
+# defineSeed
+
+Registers a set of **seed** stories that run **once, on the first (Create) deploy** of a service, to populate it with initial data — reference tables, default records, a first admin user, and so on. Unlike [migrations](./migration.md), seeds are not tracked across future deploys; they fire only when the service's stacks are first created.
+
+`defineSeed` is a convenience wrapper that expands into several lower-level config settings. It is built on [defineDeployEvent](../core/deploy-event.md), so its work is triggered by the deploy-event pipeline and ultimately runs through [askProcessEvent](../../actions/core/event/ask-process-event.md).
+
+- **What it declares:** a [global](../core/global.md) (`qpqSeeds`) holding the seed list, a [deploy event](../core/deploy-event.md) (`qpqSeeds`) that reacts to stack changes, and a [queue](../core/queue.md) (`qpqSeeds`) that executes each seed story. The queue runs **one seed at a time** (`maxConcurrentExecutions: 1`, `batchSize: 1`, `concurrency: 1`). Note there is **no** tracking key-value store — that is the key difference from `defineMigration`.
+
+```typescript
+import { defineSeed } from 'quidproquo-webserver';
+
+export default [
+  defineSeed([
+    '/entry/seeds/seedRoles::seedRoles',
+    '/entry/seeds/seedAdminUser::seedAdminUser',
+  ]),
+];
+```
+
+## How it runs
+
+The generated deploy event fires on each qualifying stack status change, but the seed logic only acts on the **Create** status. On the first deploy, every registered seed is enqueued on the `qpqSeeds` queue (which runs its story). On subsequent (Update) deploys nothing happens — seeds do not re-run.
+
+## Signature
+
+```typescript
+function defineSeed(
+  seeds: QpqFunctionRuntime[],
+): QPQConfig;
+```
+
+Like [defineMigration](./migration.md), this returns a `QPQConfig` (an array of settings) rather than a single setting, because it composes several underlying resources.
+
+## Parameters
+
+### `seeds` — `QpqFunctionRuntime[]` (required)
+
+The seed stories to run on the first deploy. Each is a `QpqFunctionRuntime`, usually a relative path string of the form `'/path/to/file::exportedFunctionName'`. A seed story receives no payload — it runs for its side effects (writing initial data). Seeds run **sequentially**, in the order the queue processes them.
+
+`defineSeed` takes no options object.
+
+## defineSeed vs defineMigration
+
+| | `defineSeed` | `defineMigration` |
+| --- | --- | --- |
+| When it runs | Only on the **first (Create)** deploy | On **every Update** deploy (matching `deployType`), and marks all as run on Create |
+| Run tracking | None (fires once at creation) | Tracked in a key-value store; each migration runs at most once |
+| Purpose | Populate initial data | Evolve / reshape existing data over time |
+| Per-entry config | Just the runtime | Runtime **plus** a `deployType` |
+
+## Related
+
+- [defineMigration](./migration.md) — the companion helper for evolving existing data on later deploys.
+- [defineDeployEvent](../core/deploy-event.md) — the lower-level deploy-time hook this is built on.
+- [askProcessEvent](../../actions/core/event/ask-process-event.md) — the pipeline that runs the seed story.
+- [defineQueue](../core/queue.md) / [defineGlobal](../core/global.md) — the resources `defineSeed` generates.

package/template/docusaurus/docs/config/webserver/seo.md

@@ -0,0 +1,72 @@
+---
+title: defineSeo
+description: Attach a server-side (edge) rendered response to a web entry path, so crawlers and social previews get real HTML instead of the SPA shell.
+---
+
+# defineSeo
+
+Defines an **SEO route**: a URL path within a [web entry](./web-entry.md) whose response is generated server-side at the CDN edge by a story, instead of being served as the static single-page-app shell. This lets crawlers, bots, and social-preview scrapers receive fully rendered HTML (title, meta tags, Open Graph, etc.) for a path, while normal users still get the SPA.
+
+- **On AWS:** the web entry's CloudFront distribution gets two Lambda@Edge functions — a **viewer-request** and an **origin-request** function — built from the `runtime` story. For each non-deprecated SEO route, a CloudFront behavior is added whose path pattern is the SEO `path` with any `{param}` placeholders turned into `*` wildcards, wiring both edge functions to that behavior. The route can use its own [cache](./cache.md) policy via `cacheSettingsName` (otherwise caching is disabled for it). Deprecated routes are still built but are **not** attached as a behavior.
+
+```typescript
+import { defineSeo } from 'quidproquo-webserver';
+
+export default [
+  defineSeo('/products/{productId}', '/entry/seo/product::renderProductSeo'),
+];
+```
+
+## Signature
+
+```typescript
+function defineSeo(
+  path: string,
+  runtime: QpqFunctionRuntime,
+  options?: QPQConfigAdvancedSeoSettings,
+): SeoQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `path` — `string` (required)
+
+The URL path pattern to render server-side, e.g. `'/products/{productId}'`. `{param}` placeholders are matched as wildcards in the CDN behavior. The `uniqueKey` of the setting is a hash of this path.
+
+### `runtime` — `QpqFunctionRuntime` (required)
+
+A reference to the story that renders the response at the edge, usually written as a relative path string in the form `'/path/to/file::exportedFunctionName'` (the same `QpqFunctionRuntime` shape used across the framework — a relative-path string or an advanced `{ basePath, relativePath, functionName }` object).
+
+### `options` — `QPQConfigAdvancedSeoSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `webEntry` | `string` | all web entries | Name of the [web entry](./web-entry.md) this SEO route belongs to. When set, the route is only attached to that web entry's distribution; when omitted, it applies to every web entry in the service. |
+| `cacheSettingsName` | `string` | caching disabled | Name of a [defineCache](./cache.md) policy for this route's CDN behavior. When omitted, the edge-rendered response is not cached. |
+| `deprecated` | `boolean` | `false` | When `true`, the edge function is still built but no CDN behavior is added — the path falls back to the normal SPA serving. |
+
+## Examples
+
+```typescript
+import { defineSeo, defineWebEntry } from 'quidproquo-webserver';
+
+export default [
+  defineWebEntry('website', {
+    buildPath: './web/dist',
+    domain: { onRootDomain: true, rootDomain: 'example.com' },
+  }),
+
+  // Render product pages server-side for crawlers & link previews
+  defineSeo('/products/{productId}', '/entry/seo/product::renderProductSeo', {
+    webEntry: 'website',
+    cacheSettingsName: 'default',
+  }),
+];
+```
+
+## Related
+
+- [defineWebEntry](./web-entry.md) — the hosted app whose paths this SEO route augments.
+- [defineCache](./cache.md) — the cache policy an SEO route can reference by name.
+- [askWebEntryInvalidateCache](../../actions/webserver/web-entry/ask-web-entry-invalidate-cache.md) — invalidate SEO paths after changing what they render.
+- **AWS implementation:** the SEO Lambda@Edge functions and CloudFront behaviors are created by `WebQpqWebserverWebEntryConstruct` in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/webserver/service-function.md

@@ -0,0 +1,69 @@
+---
+title: defineServiceFunction
+description: Define a callable service function — an RPC-style story deployed as its own Lambda, invoked directly rather than over HTTP.
+---
+
+# defineServiceFunction
+
+Defines a **service function**: a story that can be invoked directly, RPC-style, rather than being exposed as an HTTP route. Service functions are the unit of cross-service (and in-service) direct invocation — a story calls one with a typed payload and receives a typed result using [askServiceFunctionExecute](../../actions/webserver/service-function/ask-service-function-execute.md).
+
+- **On AWS:** deploys a **dedicated Lambda** (`QpqWebserverServiceFunctionConstruct` in `quidproquo-deploy-awscdk`, named `<functionName>-sfunc`) with a ~14.5-minute timeout. `askServiceFunctionExecute` invokes it directly by name — synchronously by default, or as a fire-and-forget async invocation when requested.
+
+```typescript
+import { defineServiceFunction } from 'quidproquo-webserver';
+
+export default [
+  defineServiceFunction('/src/functions/resizeImage::resizeImage'),
+];
+```
+
+## Signature
+
+```typescript
+function defineServiceFunction(
+  runtime: QpqFunctionRuntime,
+  options?: QPQConfigAdvancedServiceFunctionSettings,
+): ServiceFunctionQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `runtime` — `QpqFunctionRuntime` (required)
+
+A reference to the story the service function runs. Usually a relative path string of the form `'/path/to/file::exportedFunctionName'`. The story receives the invocation payload and returns the result.
+
+### `options` — `QPQConfigAdvancedServiceFunctionSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `functionName` | `string` | derived from the runtime's story name | The name callers use to invoke this function (the value passed as `functionName` to `askServiceFunctionExecute`). Also the function's `uniqueKey`. |
+| `virtualNetworkName` | `string` | – | Name of a `defineVirtualNetwork` (VPC) to place the Lambda in, so it can reach in-VPC data stores. |
+| `maxConcurrentExecutions` | `number` | – | Reserved concurrency — a cap and a guarantee on concurrent executions of this function. Carved out of the account's shared concurrency pool. |
+| `owner` | `CrossModuleOwner<'functionName'>` | – | Declares that the function is owned by **another** module/service. Use it to invoke a function deployed elsewhere; the deploy grants this service permission to invoke the foreign function instead of creating a new one. |
+
+## Notes
+
+- The function name defaults to the story name extracted from the runtime, so `defineServiceFunction('/src/functions/resizeImage::resizeImage')` is callable as `resizeImage` unless you override `functionName`.
+
+## Examples
+
+```typescript
+import { defineServiceFunction } from 'quidproquo-webserver';
+
+export default [
+  // Named by its story
+  defineServiceFunction('/src/functions/resizeImage::resizeImage'),
+
+  // Explicit name + capped concurrency
+  defineServiceFunction('/src/functions/sendReport::sendReport', {
+    functionName: 'send-report',
+    maxConcurrentExecutions: 5,
+  }),
+];
+```
+
+## Related
+
+- [askServiceFunctionExecute](../../actions/webserver/service-function/ask-service-function-execute.md) — invoke a service function from a story.
+- [defineRoute](./route.md) — expose a story over HTTP instead of as a direct-invoke function.
+- [defineApi](./api.md) — the service's HTTP API.

package/template/docusaurus/docs/config/webserver/state-dispatch-over-websockets.md

@@ -0,0 +1,42 @@
+---
+title: defineStateDispatchOverWebsockets
+description: Push core State-domain dispatches to connected clients over the WebSocket queue.
+---
+
+# defineStateDispatchOverWebsockets
+
+Registers an action processor override that redirects the core **State** domain's dispatch effect out to the browser. When a story runs [askStateDispatch](../../actions/core/state/ask-state-dispatch.md) (the effect that [askReduceState](../../actions/core/state/ask-reduce-state.md) emits for each action it reduces), the dispatched action is forwarded to the currently connected WebSocket client instead of being handled purely server-side. This lets a server story and a client share a reducer: state changes reduced on the server are streamed to the client so its local store stays in sync.
+
+- **Built from:** `defineActionProcessors(...)` — it overrides the `StateActionType.Dispatch` processor with the WebSocket queue's `getStateDispatch` implementation. That implementation reads the current connection info and sends a typed `StateDispatch` server message to the client over the [WebSocket queue](./web-socket-queue.md). It takes no arguments.
+
+```typescript
+import { defineStateDispatchOverWebsockets } from 'quidproquo-webserver';
+
+export default [
+  defineStateDispatchOverWebsockets(),
+];
+```
+
+## Signature
+
+```typescript
+function defineStateDispatchOverWebsockets(): QPQConfig;
+```
+
+Returns a `QPQConfig` array (a single `defineActionProcessors` setting) — spread it into your config alongside a [defineWebSocketQueue](./web-socket-queue.md).
+
+## How it works
+
+The default `StateActionType.Dispatch` processor applies a dispatched action to server-side state. This define swaps in a processor that, for each dispatch:
+
+1. reads the active WebSocket connection info (connection id and correlation id) from context;
+2. builds a `StateDispatch` server message carrying the dispatched action;
+3. sends it to the client over the WebSocket queue's outbound path.
+
+Because it operates on the connection context the [WebSocket queue](./web-socket-queue.md) establishes, use it together with [defineWebSocketQueue](./web-socket-queue.md) — the dispatch is delivered to the connection that is currently being served.
+
+## Related
+
+- [defineWebSocketQueue](./web-socket-queue.md) — provides the connection context and outbound messaging this override relies on.
+- [defineWebsocket](./websocket.md) — the raw WebSocket API underneath the queue.
+- [askStateDispatch](../../actions/core/state/ask-state-dispatch.md) and [askReduceState](../../actions/core/state/ask-reduce-state.md) — the core State-domain effects whose dispatch is redirected to the client.

package/template/docusaurus/docs/config/webserver/storage-drive-cors-settings.md

@@ -0,0 +1,73 @@
+---
+title: defineStorageDriveCorsSettings
+description: Set the browser CORS allowed-origins for a core storage drive, so cross-origin frontends can upload to / download from it directly.
+---
+
+# defineStorageDriveCorsSettings
+
+Sets the browser **CORS allowed-origins** for a [storage drive](../core/storage-drive.md) declared with `defineStorageDrive`. CORS only matters when a browser talks to the drive's bucket directly — for example a presigned-URL upload or download from your frontend — so this policy lives in the webserver config (a browser concern) and is keyed by the core drive's name rather than sitting on the core `defineStorageDrive`.
+
+- **On AWS:** the drive's S3 bucket is created with a CORS rule whose `AllowedOrigins` come from this setting (`QpqCoreStorageDriveConstruct`, wired by the web-aware deploy). The bucket allows `GET`, `HEAD`, `PUT`, and `POST` from those origins, all request headers, and exposes the `ETag` response header. When no CORS setting is declared for a drive, its allowed origins default to this service's own domain (`https://<domain>` and `https://*.<domain>`), falling back to `['*']` only when the service declares no domain at all.
+
+```typescript
+import { defineStorageDrive } from 'quidproquo-core';
+import { defineStorageDriveCorsSettings } from 'quidproquo-webserver';
+
+export default [
+  defineStorageDrive('uploads'),
+
+  // Let the app frontend upload straight to the drive
+  defineStorageDriveCorsSettings('uploads', ['https://app.example.com']),
+];
+```
+
+## Signature
+
+```typescript
+function defineStorageDriveCorsSettings(
+  storageDriveName: string,
+  allowedOrigins: string[],
+  options?: QPQConfigAdvancedStorageDriveCorsSettings,
+): StorageDriveCorsSettingsQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `storageDriveName` — `string` (required)
+
+The name of the [storage drive](../core/storage-drive.md) (as passed to `defineStorageDrive`) this CORS policy applies to. It is also the setting's `uniqueKey`, so a drive has at most one CORS setting.
+
+### `allowedOrigins` — `string[]` (required)
+
+The browser origins allowed to read/write the drive's objects via cross-origin `fetch`/`XHR`. Pass an explicit list (e.g. `['https://app.example.com']`) for cross-domain frontends, or `['*']` to allow any origin. An explicit list here overrides the service-scoped default.
+
+### `options` — `QPQConfigAdvancedStorageDriveCorsSettings` (optional)
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `deprecated` | `boolean` | Standard advanced-settings flag marking the setting as deprecated. |
+
+## Examples
+
+```typescript
+import { defineStorageDrive } from 'quidproquo-core';
+import { defineStorageDriveCorsSettings } from 'quidproquo-webserver';
+
+export default [
+  defineStorageDrive('uploads'),
+  defineStorageDrive('public-assets'),
+
+  // A specific cross-domain frontend may upload/download from 'uploads'
+  defineStorageDriveCorsSettings('uploads', ['https://app.example.com']),
+
+  // Serve 'public-assets' to any origin (e.g. cross-origin fonts/images)
+  defineStorageDriveCorsSettings('public-assets', ['*']),
+];
+```
+
+## Related
+
+- [defineStorageDrive](../core/storage-drive.md) — declares the drive this CORS policy applies to.
+- [defineWebEntry](./web-entry.md) — has its own `corsAllowedOrigins` for a web entry's served assets (a distinct concern from a drive's object CORS).
+- **Browser-direct transfers:** the presigned-URL file actions (`askFileGenerateTemporaryUploadSecureUrl`, `askFileGenerateTemporarySecureUrl` in quidproquo-core) are what a browser uses to hit the drive directly — this CORS policy is what makes those cross-origin calls succeed.
+- **AWS implementation:** `QpqCoreStorageDriveConstruct` (bucket CORS rule) in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/webserver/subdomain-redirect.md

@@ -0,0 +1,80 @@
+---
+title: defineSubdomainRedirect
+description: Redirect a subdomain to another URL via a small API Gateway + Lambda that issues HTTP redirects.
+---
+
+# defineSubdomainRedirect
+
+Redirects a **subdomain** (rooted at the service's [DNS base](./dns.md)) to another URL. A common use is redirecting `www.example.com` to `example.com`, or an old subdomain to a new destination.
+
+- **On AWS:** deploys a small redirect **Lambda** (`functionType: 'apiGatewayEventHandler_redirect'`) fronted by an **API Gateway** `LambdaRestApi` (proxy integration), plus an API Gateway custom **domain name** for the subdomain, a Route53 **`A` alias record**, and a base-path mapping (`QpqWebserverSubdomainRedirectConstruct` in `quidproquo-deploy-awscdk`). Requests hitting the subdomain are handled by the Lambda, which responds with an HTTP redirect to `redirectUrl`. The redirect config (including `subdomain` and `redirectUrl`) is passed to the Lambda as environment. An optional Cloudflare API-key secret name is carried for Cloudflare-managed DNS setups.
+
+```typescript
+import { defineSubdomainRedirect } from 'quidproquo-webserver';
+
+export default [
+  // Redirect www.<domain> to the apex
+  defineSubdomainRedirect('www', './build/redirect', 'https://example.com'),
+];
+```
+
+## Signature
+
+```typescript
+function defineSubdomainRedirect(
+  subdomain: string,
+  apiBuildPath: string,
+  redirectUrl: string,
+  addEnvironment?: boolean,
+  addFeatureEnvironment?: boolean,
+  onRootDomain?: boolean,
+  options?: QPQConfigAdvancedSubdomainRedirectSettings,
+): SubdomainRedirectQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `subdomain` | `string` | – | The subdomain to redirect from, e.g. `'www'` (the config's `uniqueKey`). |
+| `apiBuildPath` | `string` | – | Build path for the redirect handler's deployable code. |
+| `redirectUrl` | `string` | – | The destination URL requests are redirected to. |
+| `addEnvironment` | `boolean` | `true` | Whether to include the environment prefix when building the redirect's domain. |
+| `addFeatureEnvironment` | `boolean` | `true` | Whether to include the feature prefix when building the redirect's domain. |
+| `onRootDomain` | `boolean` | `true` | When `true`, the subdomain hangs off the service's base domain; when `false`, off the service-scoped domain. |
+| `options` | `QPQConfigAdvancedSubdomainRedirectSettings` | `{}` | Advanced settings. See below. |
+
+### `QPQConfigAdvancedSubdomainRedirectSettings`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `cloudflareApiKeySecretName` | `string` | – | Name of a [secret](../core/secret.md) holding a Cloudflare API key, for when the redirect's DNS is managed through Cloudflare rather than Route53. |
+
+## Examples
+
+```typescript
+import { defineSubdomainRedirect } from 'quidproquo-webserver';
+
+export default [
+  // Simple www -> apex redirect
+  defineSubdomainRedirect('www', './build/redirect', 'https://example.com'),
+
+  // Redirect an old subdomain, without env/feature prefixing, using a Cloudflare-managed zone
+  defineSubdomainRedirect(
+    'legacy',
+    './build/redirect',
+    'https://new.example.com',
+    false,
+    false,
+    true,
+    { cloudflareApiKeySecretName: 'cloudflare-api-key' },
+  ),
+];
+```
+
+## Related
+
+- [defineDns](./dns.md) — declares the base domain the subdomain hangs off.
+- [defineDomainProxy](./domain-proxy.md) — proxy a subdomain to another origin instead of redirecting it.
+- [defineCertificate](./certificate.md) — related certificate configuration.
+- [secret](../core/secret.md) — where a Cloudflare API key would be stored.