create-qpq-app 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Scaffold a new quidproquo app — npx create-qpq-app my-app",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.13",
-    "quidproquo-tsconfig": "0.1.10"
+    "quidproquo-tsconfig": "0.1.11"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-read-identity.md

@@ -0,0 +1,45 @@
+---
+title: askEventDocReadIdentity
+description: Declaratively read where an event-doc's own document lives (serviceName/basePath/id), for verbs that build links relative to their own doc.
+---
+
+# askEventDocReadIdentity
+
+The address sibling of [askEventDocReadState](./ask-event-doc-read-state.md): the story yields no payload at all, and a registered processor answers with the doc's own identity — `serviceName`, `basePath`, and `id`. Verbs written in terms of it (for example, building an `EventDocLink` relative to their own doc) stay workspace-blind, resolving whichever doc the processor is bound to.
+
+- **Action type:** `EventDocActionType.ReadIdentity`
+- **quidproquo-features ships no default processor** for this action. Calling it with no processor registered fails loudly, the same as an unbound [askEventDocReadState](./ask-event-doc-read-state.md).
+- Returns `null` until the doc has an identity to report: before the workspace initializes the slot, and always for an unsaved doc (it has no server-backed identity to resolve).
+
+```typescript
+import { askEventDocReadIdentity } from 'quidproquo-features';
+
+export function* askTemplateBuildSelfLink() {
+  const identity = yield* askEventDocReadIdentity();
+  return identity ? { serviceName: identity.serviceName, basePath: identity.basePath, id: identity.id } : null;
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocReadIdentity(): AskResponse<Nullable<EventDocWorkspaceDocumentIdentity>>;
+```
+
+## Parameters
+
+None — WHICH doc's identity to read is the answering processor's ambient context, the same as `askEventDocReadState`.
+
+## Returns
+
+`AskResponse<Nullable<EventDocWorkspaceDocumentIdentity>>` — `{ serviceName, basePath, id }`, concretely typed since every doc's identity has the same shape. `null` until the doc is bound to a real document.
+
+## Notes
+
+- This is the contract only — it carries no default behavior. A runtime that answers `askEventDocReadState` for a doc should also answer `askEventDocReadIdentity` for it.
+- In the event-doc workspace, the binding registered for a slot answers with `state.slots[slotKey].documentIdentity`, so this reflects the same identity `askInit` seeded for the slot.
+
+## Related
+
+- [askEventDocReadState](./ask-event-doc-read-state.md) — the content sibling: what the doc currently holds, rather than where it lives.
+- [askApplyEventDocEvent](./ask-apply-event-doc-event.md) — the write action this doc's verbs typically pair with.

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-read-state.md

@@ -0,0 +1,46 @@
+---
+title: askEventDocReadState
+description: Declaratively read an event-doc's current folded state, leaving WHICH doc and HOW it is resolved to a registered processor.
+---
+
+# askEventDocReadState
+
+The read counterpart of [askApplyEventDocEvent](./ask-apply-event-doc-event.md): the story yields no payload at all, and a registered processor answers with the doc's current folded state. Because it has no target of its own, verbs written in terms of it (a domain's read-to-derive-a-write action creators) run unchanged wherever a processor for it is registered, resolving whichever doc the processor is bound to.
+
+- **Action type:** `EventDocActionType.ReadState`
+- **quidproquo-features ships no default processor** for this action. Calling it with no processor registered fails loudly, the same as an unbound [askApplyEventDocEvent](./ask-apply-event-doc-event.md).
+- Returns `unknown` — the raw action can't know a slot's view type. Call it through a per-doc `createEventDocStateReader<TView>()` instead of directly, for a typed result.
+- In the event-doc workspace, the binding registered for a slot answers with the doc's current memoized view (history + pending folded and migrated to latest), so a commit earlier in the same story is visible to a read that follows it.
+
+```typescript
+import { askEventDocReadState } from 'quidproquo-features';
+
+export function* askTemplateAppendLine(line: string) {
+  const template = (yield* askEventDocReadState()) as TemplateState;
+  yield* askApplyEventDocEvent<AppendLineEffect>(TemplateEffect.AppendLine, { line: template.body ? `${template.body}\n${line}` : line });
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocReadState(): AskResponse<unknown>;
+```
+
+## Parameters
+
+None — WHICH doc to read is the answering processor's ambient context, the same as `askApplyEventDocEvent`'s target.
+
+## Returns
+
+`AskResponse<unknown>` — the doc's current folded state, untyped at this layer. Use `createEventDocStateReader<TView>()` to mint a typed `askRead<Doc>()` for a specific doc instead of casting the result by hand at every call site.
+
+## Notes
+
+- This is the contract only — it carries no default behavior. A runtime that answers `askApplyEventDocEvent` for a doc should also answer `askEventDocReadState` for it, so read-to-derive-a-write verbs work the same way commits do.
+- `createEventDocDefinition` mints the doc's fold config and api together; pair it with a standalone `createEventDocStateReader<TView>()` for the doc's typed read verb.
+
+## Related
+
+- [askApplyEventDocEvent](./ask-apply-event-doc-event.md) — the write counterpart this action mirrors.
+- [askEventDocReadIdentity](./ask-event-doc-read-identity.md) — the address sibling: where the doc lives, rather than what it currently holds.

package/template/docusaurus/docs/actions/features/web-socket-queue/ask-web-socket-queue-broadcast-message.md

@@ -0,0 +1,50 @@
+---
+title: askWebSocketQueueBroadcastMessage
+description: Push a server-initiated message to every live connection on a WebSocket queue's API.
+---
+
+# askWebSocketQueueBroadcastMessage
+
+Sends a message to **every live connection** on a named [WebSocket queue](../../../config/features/web-socket-queue.md) API. Unlike a connection-scoped send, this does not need a websocket-triggered context — the caller names the `apiName` explicitly, so any story (a storage event, a queue handler, a cron job) can push to every connected frontend. Connections whose socket died without their `onDisconnect` firing are skipped and their stale record is cleaned up automatically; a single dead connection never aborts the broadcast.
+
+```typescript
+import { askWebSocketQueueBroadcastMessage } from 'quidproquo-features';
+
+interface Announcement {
+  type: 'Announcement';
+  payload: { text: string };
+}
+
+export function* askAnnounce(text: string) {
+  yield* askWebSocketQueueBroadcastMessage<Announcement>('api', {
+    type: 'Announcement',
+    payload: { text },
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askWebSocketQueueBroadcastMessage<E extends AnyWebSocketQueueEventMessage>(
+  websocketApiName: string,
+  message: E,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `websocketApiName` | `string` | The `apiName` of the target [defineWebSocketQueue](../../../config/features/web-socket-queue.md) — every connection currently registered against this API receives the message. |
+| `message` | `E extends AnyWebSocketQueueEventMessage` | The typed event message to send, e.g. `{ type, payload }`. |
+
+## Returns
+
+`void`
+
+## Related
+
+- [askWebSocketQueueBroadcastServiceUpdated](./ask-web-socket-queue-broadcast-service-updated.md) — a typed wrapper around this for the built-in `ServiceUpdated` message.
+- [defineWebSocketQueue](../../../config/features/web-socket-queue.md) — declares the WebSocket queue API this broadcasts on.
+- [askServiceRequest](./ask-service-request.md) — an RPC-style request/response over the same queue, addressed to one service rather than broadcast to every connection.

package/template/docusaurus/docs/actions/features/web-socket-queue/ask-web-socket-queue-broadcast-service-updated.md

@@ -0,0 +1,41 @@
+---
+title: askWebSocketQueueBroadcastServiceUpdated
+description: Tell every connected frontend that a service's deployed artifacts changed, so it can offer a module reload.
+---
+
+# askWebSocketQueueBroadcastServiceUpdated
+
+Broadcasts a `ServiceUpdated` message to every live connection on a [WebSocket queue](../../../config/features/web-socket-queue.md) API, naming the service whose deployed artifacts changed (for example, a new views bundle going live). A typed wrapper around [askWebSocketQueueBroadcastMessage](./ask-web-socket-queue-broadcast-message.md) for this one built-in message type.
+
+```typescript
+import { askWebSocketQueueBroadcastServiceUpdated } from 'quidproquo-features';
+
+export function* askNotifyDeploy(serviceName: string) {
+  yield* askWebSocketQueueBroadcastServiceUpdated('api', serviceName);
+}
+```
+
+## Signature
+
+```typescript
+function* askWebSocketQueueBroadcastServiceUpdated(
+  websocketApiName: string,
+  serviceName: string,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `websocketApiName` | `string` | The `apiName` of the target [defineWebSocketQueue](../../../config/features/web-socket-queue.md) — every connection currently registered against this API receives the message. |
+| `serviceName` | `string` | The qpq service (module) whose deployed artifacts changed. Sent as `payload.serviceName` on a `WebSocketQueueServerMessageEventType.ServiceUpdated` message. |
+
+## Returns
+
+`void`
+
+## Related
+
+- [askWebSocketQueueBroadcastMessage](./ask-web-socket-queue-broadcast-message.md) — the untyped broadcast this wraps.
+- [defineWebSocketQueue](../../../config/features/web-socket-queue.md) — declares the WebSocket queue API this broadcasts on.

package/template/docusaurus/docs/actions/webserver/email/_category_.json

@@ -0,0 +1 @@
+{ "label": "Email", "link": { "type": "generated-index", "description": "Actions for sending email from a service." } }

package/template/docusaurus/docs/actions/webserver/email/ask-email-send-email.md

@@ -0,0 +1,85 @@
+---
+title: askEmailSendEmail
+description: Send an email from a domain declared with defineEmailSender.
+---
+
+# askEmailSendEmail
+
+Sends an email. The `from` address must be under a domain declared with [defineEmailSender](../../../config/webserver/email-sender.md) — the deploy grants the service's role permission to send only from its own verified identity domains.
+
+- **Action type:** `EmailActionType.SendEmail`
+- **On AWS:** sent through **SES v2** (`SendEmailCommand`). `bcc` addresses are only ever placed in the SES `Destination`, never written into a message header, so other recipients can't see them. When `attachments` are provided the message is built as a raw MIME email (multipart/mixed wrapping a multipart/alternative body); otherwise it's sent as SES "Simple" content. While the SES account is in sandbox mode, recipients also need to be listed with [defineEmailSenderAllowList](../../../config/config-aws/email-sender-allow-list.md) and verified in the SES console.
+
+```typescript
+import { askEmailSendEmail } from 'quidproquo-webserver';
+
+export function* askSendWelcomeEmail(to: string) {
+  const messageId = yield* askEmailSendEmail({
+    from: 'noreply@example.com',
+    to: [to],
+    subject: 'Welcome!',
+    bodyText: 'Thanks for signing up.',
+    bodyHtml: '<p>Thanks for signing up.</p>',
+  });
+
+  return messageId;
+}
+```
+
+## Signature
+
+```typescript
+function* askEmailSendEmail(payload: EmailSendEmailActionPayload): AskResponse<string>;
+```
+
+## Parameters
+
+### `payload` — `EmailSendEmailActionPayload` (required)
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `from` | `string` | Sender address. Must be under a domain declared with `defineEmailSender`. |
+| `to` | `string[]` | Recipient addresses. |
+| `cc` | `string[]` (optional) | Addresses copied on the message. |
+| `bcc` | `string[]` (optional) | Addresses blind-copied on the message. Never written into a message header, on AWS or otherwise. |
+| `replyTo` | `string[]` (optional) | Addresses to route replies to. |
+| `subject` | `string` | Message subject. |
+| `bodyText` | `string` (optional) | Plain-text body. At least one of `bodyText` / `bodyHtml` is required. |
+| `bodyHtml` | `string` (optional) | HTML body. At least one of `bodyText` / `bodyHtml` is required. |
+| `attachments` | `QPQBinaryData[]` (optional) | Files to attach, each `{ base64Data, filename, mimetype?, contentDisposition? }`. Presence of any attachment switches the message to the raw MIME send path. |
+
+## Returns
+
+`string` — the provider's message id for the sent email (SES's `MessageId`), or `''` if the provider didn't return one.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `EmailSendEmailErrorTypeEnum.MessageRejected` | SES rejected the message content. |
+| `EmailSendEmailErrorTypeEnum.SenderNotVerified` | The `from` domain isn't a verified SES identity (AWS `MailFromDomainNotVerifiedException`). |
+| `EmailSendEmailErrorTypeEnum.AccountSuspended` | The SES account is suspended (AWS `AccountSuspendedException`). |
+| `EmailSendEmailErrorTypeEnum.SendingPaused` | Sending is paused for the account (AWS `SendingPausedException`). |
+| `EmailSendEmailErrorTypeEnum.Throttled` | The send rate was exceeded (AWS `TooManyRequestsException`). |
+| `EmailSendEmailErrorTypeEnum.LimitExceeded` | A sending limit was exceeded (AWS `LimitExceededException`). |
+| `EmailSendEmailErrorTypeEnum.BadRequest` | The request was otherwise invalid (AWS `BadRequestException`). |
+
+Wrap the call in [askCatch](../../../actions/core/system/ask-catch.md) to handle these without unwinding the story:
+
+```typescript
+import { askCatch } from 'quidproquo-core';
+import { askEmailSendEmail, EmailSendEmailErrorTypeEnum } from 'quidproquo-webserver';
+
+export function* askTrySendEmail(payload) {
+  const outcome = yield* askCatch(askEmailSendEmail(payload));
+  if (!outcome.success && outcome.error.errorType === EmailSendEmailErrorTypeEnum.Throttled) {
+    // back off and retry later
+  }
+}
+```
+
+## Related
+
+- [defineEmailSender](../../../config/webserver/email-sender.md) — declares the verified sending domain this action requires.
+- [defineEmailSenderAllowList](../../../config/config-aws/email-sender-allow-list.md) — recipient addresses allowed while the SES account is in sandbox mode.
+- [askCatch](../../../actions/core/system/ask-catch.md) — catch the errors above.

package/template/docusaurus/docs/config/config-aws/email-sender-allow-list.md

@@ -0,0 +1,45 @@
+---
+title: defineEmailSenderAllowList
+description: Recipient addresses a service is allowed to email while its SES account is in sandbox mode.
+---
+
+# defineEmailSenderAllowList
+
+Declares recipient addresses a service is allowed to send to while its SES account is still in **sandbox mode**. In sandbox, SES authorizes a send against the recipient's identity as well as the sender's, so [defineEmailSender](../webserver/email-sender.md)'s exact-ARN send grant needs each recipient identity listed too. The addresses must also be verified identities in the SES console (sandbox requires that anyway).
+
+This is an AWS-specific concession, not a portable email concept, which is why it lives in `quidproquo-config-aws` keyed by the same `rootDomain` as `defineEmailSender` rather than on that webserver setting directly. Once the account has SES production access this setting does nothing useful and can be deleted.
+
+```typescript
+import { defineEmailSender } from 'quidproquo-webserver';
+import { defineEmailSenderAllowList } from 'quidproquo-config-aws';
+
+export default [
+  defineEmailSender('example.com'),
+
+  defineEmailSenderAllowList('example.com', ['joe@external.com', 'test@external.com']),
+];
+```
+
+## Signature
+
+```typescript
+function defineEmailSenderAllowList(
+  rootDomain: string,
+  allowedEmailAddresses: string[],
+): EmailSenderAllowListQPQConfigSetting;
+```
+
+## Parameters
+
+### `rootDomain` — `string` (required)
+
+The `rootDomain` of the matching [defineEmailSender](../webserver/email-sender.md) this allow-list applies to.
+
+### `allowedEmailAddresses` — `string[]` (required)
+
+Recipient addresses to grant sandbox send access to. Multiple calls for the same `rootDomain` are additive.
+
+## Related
+
+- [defineEmailSender](../webserver/email-sender.md) — the sending domain this allow-list is keyed by.
+- [askEmailSendEmail](../../actions/webserver/email/ask-email-send-email.md) — the action these addresses need to be reachable from.

package/template/docusaurus/docs/config/features/admin-settings.md

@@ -54,6 +54,7 @@ export interface QPQConfigAdvancedLogSettings extends QPQConfigAdvancedSettings
   logRetentionDays?: number;
   coldStorageAfterDays?: number;
   services?: string[];
+  maintenanceWebsocketApiName?: string;
 }
 ```
 
@@ -62,6 +63,7 @@ export interface QPQConfigAdvancedLogSettings extends QPQConfigAdvancedSettings
 | `logRetentionDays` | `number` | – (no expiry) | How many days to keep the raw log objects on the logs storage drive before they are deleted. When unset, logs never expire. If `coldStorageAfterDays` is set, the effective retention is padded so that it is at least `coldStorageAfterDays + 180` days — logs always outlive the cold-storage transition window. |
 | `coldStorageAfterDays` | `number` | – (no transition) | When greater than 0, adds a lifecycle rule transitioning log objects to the `DEEP_COLD_STORAGE` tier after this many days, to cut storage cost for old logs. |
 | `services` | `string[]` | `[]` | The list of service names the admin dashboard should surface, exposed as the `qpq-serviceNames` global. Returned by the `/admin/services` route. |
+| `maintenanceWebsocketApiName` | `string` | `''` | Name of the **application** [WebSocket queue](./web-socket-queue.md) (its `apiName`, not the admin's own socket) that maintenance state broadcasts on. Unset means maintenance mutations skip broadcasting. |
 | `deprecated` | `boolean` | `false` | Inherited from `QPQConfigAdvancedSettings`; marks the log storage drives and key-value stores as deprecated. |
 
 ## What it declares
@@ -72,6 +74,7 @@ export interface QPQConfigAdvancedLogSettings extends QPQConfigAdvancedSettings
 - **Log indexes** — key-value stores for correlations (indexed by `runtimeType` and `fromCorrelation`, both sorted by `startedAt`, with a `ttl` attribute), log messages, and a log list.
 - **Auth routes** — `POST /login`, `POST /refreshToken`, `POST /challenge`, authenticated against the [admin user directory](./admin-user-directory.md).
 - **Log routes** — `GET /admin/services`, `POST /log/list`, `GET /log/{correlationId}`, its `/toggle`, `/children`, `/hierarchies`, `/downloadurl`, and the log-log list — all (except the service list) requiring an admin token.
+- **Maintenance collection** — an [event-doc collection](./event-doc.md) (`defineEventDoc`) mounted at `/maintenance`, admin-authenticated, storing maintenance windows as an append-only update log. Every append re-broadcasts the active maintenance set to every connection on the `maintenanceWebsocketApiName` application WebSocket queue (via its `onAppend` hook); a newly-opened connection gets the same set pre-auth through that queue's `onConnected` sync.
 - **Log chat** — a `defineEventDocAi` instance scoped to `docId` = log correlation id, with two tools (`getLogActions`, `getLogAction`) instead of the log's JSON pasted into the prompt. Runs on `AiModel.ClaudeSonnet46` over the same admin WebSocket connection, not a separate HTTP route.
 - **WebSocket sync** — an admin event bus (`qpq-admin-wsq`), a `defineWebSocketQueue`, and queues that fan out client messages (config sync, mark-log-checked, refresh-metadata) using `WebsocketAdminClientMessageEventType`.
 - **Alarms** — a `defineNotifyError` publishing to an `admin-notifier` event bus, with a queue handling its Error / Timeout / Throttle events.
@@ -100,4 +103,6 @@ export default [
 - [defineAdminUserDirectory](./admin-user-directory.md) — the directory admins authenticate against; declare it alongside these settings.
 - [defineAdminSessionEventDoc](./admin-session-event-doc.md) — the per-login admin session document, spread in by this define.
 - [askAdminGetLogs](../../actions/webserver/admin/ask-admin-get-logs.md), [askAdminGetLog](../../actions/webserver/admin/ask-admin-get-log.md), [askAdminGetLogMetadata](../../actions/webserver/admin/ask-admin-get-log-metadata.md) — the actions the admin log routes are built from.
+- [defineEventDoc](./event-doc.md) — the helper the maintenance collection is declared with.
+- [defineWebSocketQueue](./web-socket-queue.md) — declares the application WebSocket queue named by `maintenanceWebsocketApiName`, including its `onConnected` pre-auth sync.
 - [defineStorageDrive](../core/storage-drive.md), [defineKeyValueStore](../core/key-value-store.md), [defineQueue](../core/queue.md), [defineEventBus](../core/event-bus.md) — the core settings this feature composes.

package/template/docusaurus/docs/config/features/event-doc-routes.md

@@ -61,6 +61,7 @@ The single `options` argument is an `EventDocRoutesOptions`:
 | `eventValidator` | `string` | – | Name of a registered inline function (see `defineInlineFunction`). When set, every append invokes it with `{ event, events }` to reject lifecycle- or payload-invalid events before they reach the log. The frontend editor runs the same rule for instant feedback. |
 | `eventRenderer` | `string` | – | Name of a registered inline function. When set, a `GET {basePath}/{id}/render` route is mounted; it invokes the renderer with the document's full `{ events }` log, which folds + renders to HTML. |
 | `onPublish` | `string` | – | Name of a registered inline function. When set, every successful append of a Publish event invokes it with `{ docId, event, summary }`, after the event is durably written and the summary re-derived. This is the seam for syncing a folded document into a materialized read model. Errors propagate to the caller: the event has landed but the side effect did not, so the caller learns the read model may be stale. |
+| `onAppend` | `string` | – | Name of a registered inline function. When set, EVERY successful append (domain events and lifecycle events alike) invokes it with `{ docId, event, summary, events }`, after the event is durably written and the summary re-derived. This is the seam for reacting to any mutation (e.g. broadcasting the doc's fresh fold). Runs after `onPublish` when both fire on the same Publish event. Errors propagate to the caller: the event has landed but the side effect did not. |
 | `scopeResolver` | `string` | – | Name of a registered inline function. When set, every route invokes it with `{ event }` before running; a non-null result becomes the ambient storage scope for the whole request, transparently partitioning the collection's stores and assets (e.g. per-tenant). Null means unscoped. Omit for collections that never partition. |
 | `excludeRoutes` | `EventDocRouteName[]` | `[]` | Route names to leave unmounted (`'list' \| 'get' \| 'listEvents' \| 'render' \| 'create' \| 'appendEvent' \| 'createAsset' \| 'getAsset' \| 'remove'`). For a collection that must own one of these itself instead of using the stock behavior — e.g. a `create` that must also perform some side effect the stock controller doesn't know about. |
 

package/template/docusaurus/docs/config/features/event-doc.md

@@ -48,6 +48,7 @@ function defineEventDoc(options: EventDocRoutesOptions): QPQConfig;
 | `eventValidator` | `string` | no | Inline-function name run on every append to reject invalid events. |
 | `eventRenderer` | `string` | no | Inline-function name that folds + renders the log to HTML; mounting it adds a `GET {basePath}/{id}/render` route. |
 | `onPublish` | `string` | no | Inline-function name invoked with `{ docId, event, summary }` after every successful Publish append: the seam for syncing the folded document into a materialized read model. |
+| `onAppend` | `string` | no | Inline-function name invoked with `{ docId, event, summary, events }` after EVERY successful append (domain events and lifecycle events alike): the seam for reacting to any mutation. Runs after `onPublish` when both fire on the same Publish event. |
 | `scopeResolver` | `string` | no | Inline-function name every route invokes with `{ event }` to resolve the request's ambient storage scope (e.g. per-tenant); null means unscoped. |
 
 ## Examples

package/template/docusaurus/docs/config/features/web-socket-queue.md

@@ -68,6 +68,7 @@ export interface QPQConfigAdvancedWebsocketQueueSettings extends QPQConfigAdvanc
   owner?: CrossModuleOwnerWithNoResourceOverride;
   userDirectoryName?: string;
   connectionScopeResolver?: string;
+  onConnected?: string;
 }
 ```
 
@@ -75,6 +76,7 @@ export interface QPQConfigAdvancedWebsocketQueueSettings extends QPQConfigAdvanc
 | --- | --- | --- | --- |
 | `userDirectoryName` | `string` | `''` | Name of the [user directory](../core/user-directory.md) used to authenticate clients (stored in the `qpq-wsq-kvs-name-<apiName>` global). Enables the authenticate client/server message flow. |
 | `connectionScopeResolver` | `string` | `''` | Name of a registered [inline function](../core/inline-function.md) invoked with `{ userId, requestedScope }` on **every** Authenticate message, whether or not it claims a storage scope (stored in the `qpq-wsq-scope-resolver-<apiName>` global). It returns the effective scope to store on the connection (e.g. a membership-checked tenant scope for a claim, or the user's own scope for no claim), or throws to reject the authenticate. A scope claim with no resolver configured is rejected outright, leaving the connection unauthenticated. |
+| `onConnected` | `string` | `''` | Name of a registered [inline function](../core/inline-function.md) invoked with `{ connectionId }` as soon as a connection opens, **before** any authenticate — so it must only push public state (e.g. broadcasting an already-active maintenance notice to a pre-login client). Runs in the websocket-owning service; failures are swallowed so a sync problem never breaks the connect. |
 | `owner` | `CrossModuleOwnerWithNoResourceOverride` | – | Declares the queue's resources as owned by another module/service, so this service references them instead of deploying its own. Applied to both the WebSocket API and the connection store. |
 | `deprecated` | `boolean` | `false` | Inherited from `QPQConfigAdvancedSettings`; when set, the underlying WebSocket API is not deployed. |
 
@@ -88,4 +90,5 @@ A `QPQConfig` array containing: three globals, the connection [key-value store](
 - [defineStateDispatchOverWebsockets](./state-dispatch-over-websockets.md) — routes core State-domain dispatches to clients through this queue.
 - [defineTenantedWebSocketQueue](./tenanted-web-socket-queue.md) — this define with the tenant connection-scope resolver pre-wired.
 - [askWebsocketSendMessage](../../actions/webserver/websocket/ask-websocket-send-message.md) — send a raw message to a connection on the queue's API.
+- [askWebSocketQueueBroadcastMessage](../../actions/features/web-socket-queue/ask-web-socket-queue-broadcast-message.md), [askWebSocketQueueBroadcastServiceUpdated](../../actions/features/web-socket-queue/ask-web-socket-queue-broadcast-service-updated.md) — push a server-initiated message to every live connection on this queue's API.
 - [defineEventBus](../core/event-bus.md), [defineKeyValueStore](../core/key-value-store.md), [defineUserDirectory](../core/user-directory.md) — the underlying resources it depends on.

package/template/docusaurus/docs/config/webserver/email-sender.md

@@ -0,0 +1,43 @@
+---
+title: defineEmailSender
+description: Declare a domain a service is allowed to send email from.
+---
+
+# defineEmailSender
+
+Declares a domain the service can send email from with [askEmailSendEmail](../../actions/webserver/email/ask-email-send-email.md). The domain must live under a base declared with [defineDns](./dns.md) — deploy resolves it the same way (environment/feature prefixed) before creating the sending identity.
+
+- **On AWS:** creates an SES `EmailIdentity` for the resolved domain in its Route53 hosted zone (DKIM records land there automatically), and scopes the service role's `ses:SendEmail` / `ses:SendRawEmail` grant to that identity's exact ARN. `ses:SendRawEmail` is needed for emails with attachments, which are sent as raw MIME. No grant or identity is created for services that declare no `defineEmailSender`.
+
+```typescript
+import { defineDns, defineEmailSender } from 'quidproquo-webserver';
+
+export default [
+  defineDns('example.com'),
+  defineEmailSender('example.com'),
+];
+```
+
+## Signature
+
+```typescript
+function defineEmailSender(
+  rootDomain: string,
+): EmailSenderQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `rootDomain` — `string` (required)
+
+The domain to send from, resolved the same way as [defineDns](./dns.md)'s `dnsBase` (environment/feature prefixed). This value is also the config's `uniqueKey`, so a service declares one sender per root domain.
+
+## Returns
+
+An `EmailSenderQPQWebServerConfigSetting` config entry. Deploy reads every declared entry with `qpqWebServerUtils.getEmailSenderSettings` to create the SES identities and IAM grants.
+
+## Related
+
+- [askEmailSendEmail](../../actions/webserver/email/ask-email-send-email.md) — send email from a domain declared here.
+- [defineDns](./dns.md) — the base domain this sender's `rootDomain` resolves against.
+- [defineEmailSenderAllowList](../config-aws/email-sender-allow-list.md) — recipient addresses allowed while the SES account is in sandbox mode.

package/template/package.json

@@ -32,7 +32,6 @@
     "@chakra-ui/cli": "^3.0.0",
     "@rspack/core": "^2.1.2",
     "@sparticuz/chromium": "^112.0.2",
-    "@types/adm-zip": "^0.5.0",
     "@types/jsonwebtoken": "^9.0.4",
     "@types/lodash": "^4.14.191",
     "@types/luxon": "^3.4.2",
@@ -62,10 +61,9 @@
     "@types/fs-extra": "^11.0.1",
     "@types/glob": "^8.1.0",
     "@xyflow/react": "^12.10.0",
-    "adm-zip": "^0.5.10",
-    "aws-cdk-lib": "^2.210.0",
+    "aws-cdk-lib": "^2.262.0",
     "chakra-react-select": "^6.1.3",
-    "constructs": "^10.1.164",
+    "constructs": "^10.7.1",
     "core-js": "^3.36.1",
     "dotenv": "^16.0.3",
     "jsonata": "^2.2.1",