create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/webserver/route-auth-validation/ask-route-auth-validation-decode.md

@@ -0,0 +1,65 @@
+---
+title: askRouteAuthValidationDecode
+description: Decode and validate a route's incoming auth token against its route auth settings, returning the decoded access token.
+---
+
+# askRouteAuthValidationDecode
+
+Decodes and validates the **auth token on an incoming HTTP request** against a route's auth settings, and returns the decoded access token (or `null` when there is no valid token). This is the action the webserver runs to authenticate a route before its handler story executes; the decoding is driven by the service's auth system (see `defineAuthSystem`).
+
+- **Action type:** `RouteAuthValidationActionType.Decode`
+
+```typescript
+import { askRouteAuthValidationDecode } from 'quidproquo-webserver';
+
+export function* askAuthenticateRequest(event, routeAuthSettings) {
+  const decoded = yield* askRouteAuthValidationDecode(event, routeAuthSettings, false);
+
+  if (!decoded || !decoded.wasValid) {
+    // no token, or token failed validation
+    return null;
+  }
+
+  return decoded; // { userId, username, roles, ... }
+}
+```
+
+## Signature
+
+```typescript
+function* askRouteAuthValidationDecode(
+  event: HTTPEvent,
+  routeAuthSettings: RouteAuthSettings,
+  ignoreExpiration: boolean,
+): AskResponse<DecodedAccessToken | null>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `event` | `HTTPEvent` | The incoming HTTP request event carrying the auth token (typically a bearer token in the headers). |
+| `routeAuthSettings` | `RouteAuthSettings` | The route's auth settings — `userDirectoryName`, `scopes`, `apiKeys` — used to decide which user directory the token is validated against. See [defineRoute](../../../config/webserver/route.md). |
+| `ignoreExpiration` | `boolean` | When `true`, an expired token is still decoded (its `wasValid` reflects other checks). When `false`, expiration is enforced. |
+
+## Returns
+
+`DecodedAccessToken | null` — `null` when there is no token to decode. Otherwise the decoded token:
+
+```typescript
+interface DecodedAccessToken {
+  userId: string;
+  username: string;
+  exp: number;          // expiry, Unix timestamp in seconds
+  roles?: string[];
+  userDirectory: string;
+  wasValid: boolean;    // whether the token passed validation
+}
+```
+
+Always check `wasValid` — a token can be decoded but still have failed validation.
+
+## Related
+
+- [defineRoute](../../../config/webserver/route.md) — declares the `routeAuthSettings` this action validates against.
+- [askUserDirectoryDecodeAccessToken](../../core/user-directory/ask-user-directory-decode-access-token.md) — the underlying user-directory token decode.

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

@@ -0,0 +1 @@
+{ "label": "Service", "link": { "type": "generated-index", "description": "Send RPC-style requests to another qpq service." } }

package/template/docusaurus/docs/actions/webserver/service/ask-service-request.md

@@ -0,0 +1,69 @@
+---
+title: askServiceRequest
+description: Send an RPC-style request to another qpq service, identified by a method name, and receive its typed response.
+---
+
+# askServiceRequest
+
+Sends an **RPC-style request to another qpq service**, identified by a service name and a method name, with a typed payload, and returns the service's typed response. It is the low-level action behind the `createServiceRequester` helper, which binds a service + method into a reusable, typed requester.
+
+- **Action type:** `ServiceActionType.Request`
+- The request is dispatched as a `qpq/serviceRequest/<serviceName>/<method>` message and its correlated response is awaited. In a browser (quidproquo-web-react) client this travels over the app's WebSocket queue connection; the response is returned when the correlated reply arrives.
+
+```typescript
+import { askServiceRequest } from 'quidproquo-webserver';
+
+interface GetQuoteRequest { symbol: string; }
+interface GetQuoteResponse { symbol: string; price: number; }
+
+export function* askGetQuote(symbol: string) {
+  const quote = yield* askServiceRequest<GetQuoteRequest, GetQuoteResponse>(
+    'market',   // service name
+    'getQuote', // method
+    { symbol },
+  );
+
+  return quote.price;
+}
+```
+
+Prefer `createServiceRequester` for a typed, reusable wrapper:
+
+```typescript
+import { createServiceRequester } from 'quidproquo-webserver';
+
+// Bind the service + method once, with request/response types
+const askGetQuote = createServiceRequester<GetQuoteRequest, GetQuoteResponse>('market', 'getQuote');
+
+export function* askQuotePrice(symbol: string) {
+  const quote = yield* askGetQuote({ symbol });
+  return quote.price;
+}
+```
+
+## Signature
+
+```typescript
+function* askServiceRequest<TPayload, TResponse>(
+  serviceName: string,
+  method: string,
+  payload: TPayload,
+): AskResponse<TResponse>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `serviceName` | `string` | Name of the target service. |
+| `method` | `string` | The service method to invoke — combined with `serviceName` into the request event type. |
+| `payload` | `TPayload` | The typed request payload. |
+
+## Returns
+
+`TResponse` — the typed response returned by the target service's handler for that method.
+
+## Related
+
+- [askServiceFunctionExecute](../service-function/ask-service-function-execute.md) — direct Lambda-invoke of a named service function.
+- [askCatch](../../core/system/ask-catch.md) — catch errors returned by the service handler.

package/template/docusaurus/docs/actions/webserver/service-function/_category_.json

@@ -0,0 +1 @@
+{ "label": "Service Function", "link": { "type": "generated-index", "description": "Invoke callable service functions (RPC-style stories) from within a story." } }

package/template/docusaurus/docs/actions/webserver/service-function/ask-service-function-execute.md

@@ -0,0 +1,58 @@
+---
+title: askServiceFunctionExecute
+description: Invoke a service function (an RPC-style story) by name and receive its typed result.
+---
+
+# askServiceFunctionExecute
+
+Invokes a [service function](../../../config/webserver/service-function.md) — a story deployed for direct, RPC-style invocation — by name, passing a typed payload and receiving the function's typed result. Use it to call another service's (or your own service's) business logic directly, without going through an HTTP route.
+
+- **Action type:** `ServiceFunctionActionType.Execute`
+- **On AWS:** invokes the target function's dedicated Lambda (`<functionName>-sfunc`) directly by name. When `isAsync` is `false` (the default) the call is synchronous and returns the function's result; when `true` it is a fire-and-forget async invocation that resolves without a result.
+
+```typescript
+import { askServiceFunctionExecute } from 'quidproquo-webserver';
+
+interface ResizeRequest { drive: string; filepath: string; width: number; }
+interface ResizeResult { thumbnailPath: string; }
+
+export function* askMakeThumbnail(filepath: string) {
+  const result = yield* askServiceFunctionExecute<ResizeResult, ResizeRequest>(
+    'media',        // service name
+    'resizeImage',  // function name
+    { drive: 'uploads', filepath, width: 256 },
+  );
+
+  return result.thumbnailPath;
+}
+```
+
+## Signature
+
+```typescript
+function* askServiceFunctionExecute<R, T>(
+  service: string,
+  functionName: string,
+  payload: T,
+  isAsync?: boolean,
+): AskResponse<R>;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `service` | `string` | – | Name of the service that owns the target function. |
+| `functionName` | `string` | – | Name of the [service function](../../../config/webserver/service-function.md) to invoke (its `functionName`, which defaults to the story name). |
+| `payload` | `T` | – | The typed payload passed to the function's story. |
+| `isAsync` | `boolean` | `false` | When `false`, wait for and return the result. When `true`, invoke fire-and-forget and resolve without a result. |
+
+## Returns
+
+`R` — the value returned by the invoked function's story. When `isAsync` is `true` there is no meaningful result (the async invocation resolves without waiting for the function to finish).
+
+## Related
+
+- [defineServiceFunction](../../../config/webserver/service-function.md) — declares the function this action invokes.
+- [askServiceRequest](../service/ask-service-request.md) — a related request to another service, dispatched by method name.
+- [askCatch](../../core/system/ask-catch.md) — catch errors thrown by the invoked function.

package/template/docusaurus/docs/actions/webserver/web-entry/_category_.json

@@ -0,0 +1 @@
+{ "label": "Web Entry", "link": { "type": "generated-index", "description": "Action requesters for hosted web apps (SPAs / static sites) served through a CDN." } }

package/template/docusaurus/docs/actions/webserver/web-entry/ask-web-entry-invalidate-cache.md

@@ -0,0 +1,53 @@
+---
+title: askWebEntryInvalidateCache
+description: Invalidate the CDN cache for a hosted web entry so viewers pick up freshly deployed assets.
+---
+
+# askWebEntryInvalidateCache
+
+Invalidates the CDN cache for a [web entry](../../../config/webserver/web-entry.md) so that cached copies of the given paths are dropped and the next request re-fetches them from origin. Use this after uploading a new build to a web entry's storage drive, so viewers see the new assets without waiting for the [cache](../../../config/webserver/cache.md) TTL to expire.
+
+- **Action type:** `WebEntryActionType.InvalidateCache`
+- **On AWS:** looks up the CloudFront distribution deployed for the named web entry (via its CloudFormation export) and issues a CloudFront `CreateInvalidation` for the supplied paths. The caller reference is derived from a hash of the paths plus the current timestamp, so repeated invalidations of the same paths are always accepted as distinct requests.
+
+```typescript
+import { askWebEntryInvalidateCache } from 'quidproquo-webserver';
+
+export function* askPublishSite() {
+  // Drop the SPA shell and manifest so a new deploy is served immediately
+  yield* askWebEntryInvalidateCache('website', '/index.html', '/mf-manifest.json');
+}
+```
+
+Passing no paths issues an invalidation with an empty path set (nothing is invalidated); pass `'/*'` to invalidate everything the distribution has cached.
+
+## Signature
+
+```typescript
+function* askWebEntryInvalidateCache(
+  webEntryName: string,
+  ...paths: string[]
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `webEntryName` | `string` | Name of the web entry to invalidate — must match the `name` passed to [defineWebEntry](../../../config/webserver/web-entry.md). This resolves to that web entry's CDN distribution. |
+| `...paths` | `string[]` | One or more path patterns to invalidate, each a leading-slash absolute path (e.g. `'/index.html'`, `'/assets/*'`, `'/*'`). Collected from the rest arguments into an array. |
+
+## Returns
+
+`void` — the story resumes once the invalidation request has been accepted by the CDN. Note this returns as soon as the invalidation is *submitted*; propagation across CDN edge locations completes asynchronously.
+
+## Notes
+
+- The deploy grants each service role permission to create invalidations only on that service's own web-entry distributions, so this action can be called from within the same service that owns the web entry.
+- CDN providers meter invalidations (CloudFront gives a monthly free allowance and charges beyond it), so prefer invalidating specific paths over `'/*'` where practical, or lean on the [cache](../../../config/webserver/cache.md) TTLs and `ignoreCache` patterns instead.
+
+## Related
+
+- [defineWebEntry](../../../config/webserver/web-entry.md) — declares the hosted web app whose cache this invalidates.
+- [defineCache](../../../config/webserver/cache.md) — the CDN cache policy (TTLs) an invalidation forces past.
+- [defineSeo](../../../config/webserver/seo.md) — server-side (edge) rendering attached to a web entry's paths.

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

@@ -0,0 +1 @@
+{ "label": "WebSocket", "link": { "type": "generated-index", "description": "Actions for sending messages to connected WebSocket clients." } }

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

@@ -0,0 +1,71 @@
+---
+title: askWebsocketSendMessage
+description: Send a message to a single connected WebSocket client by connection id.
+---
+
+# askWebsocketSendMessage
+
+Sends a payload to one connected WebSocket client, addressed by its `connectionId`. Use it from any story to push data out over a [WebSocket API](../../../config/webserver/websocket.md) — for example replying to a client's message or broadcasting an update to a connection you recorded earlier.
+
+- **Action type:** `WebsocketActionType.SendMessage`
+- **On AWS:** the payload is `JSON.stringify`'d and delivered through the **API Gateway Management API** `PostToConnection` call against the resolved WebSocket API endpoint. A throttling response from the service surfaces as `Throttled`; sending to a connection that has already closed surfaces as `Disconnected`.
+
+```typescript
+import { askWebsocketSendMessage } from 'quidproquo-webserver';
+
+export function* askNotifyClient(connectionId: string) {
+  yield* askWebsocketSendMessage('api', connectionId, {
+    type: 'notification',
+    text: 'Your export is ready',
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askWebsocketSendMessage<T>(
+  websocketApiName: string,
+  connectionId: string,
+  payload: T,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `websocketApiName` | `string` | The `apiName` of the target [WebSocket API](../../../config/webserver/websocket.md) (the `apiName` option of [defineWebsocket](../../../config/webserver/websocket.md), or the `apiName` argument to [defineWebSocketQueue](../../../config/webserver/web-socket-queue.md)). Identifies which deployed API the connection belongs to. |
+| `connectionId` | `string` | Identifier of the client connection to send to. You receive this on the `WebsocketEvent` in your connect/message handlers; persist it (e.g. keyed by user) if you need to send outside the request that created it. |
+| `payload` | `T` | The message to send. Serialized to JSON before transmission, so any JSON-serializable value works. |
+
+## Returns
+
+`void` — the story resumes once the message has been handed to the platform for delivery.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `WebsocketSendMessageErrorTypeEnum.Throttled` | The platform rate-limited the send (AWS `ThrottlingException`, "Rate exceeded"). |
+| `WebsocketSendMessageErrorTypeEnum.Disconnected` | The target connection no longer exists — the client has disconnected (AWS `GoneException`). |
+
+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 { askWebsocketSendMessage, WebsocketSendMessageErrorTypeEnum } from 'quidproquo-webserver';
+
+export function* askTrySend(connectionId: string, payload: unknown) {
+  const outcome = yield* askCatch(askWebsocketSendMessage('api', connectionId, payload));
+  if (!outcome.success && outcome.error.errorType === WebsocketSendMessageErrorTypeEnum.Disconnected) {
+    // client is gone — drop the stored connection id
+  }
+}
+```
+
+## Related
+
+- [defineWebsocket](../../../config/webserver/websocket.md) — declares the WebSocket API and its connect/disconnect/message handlers.
+- [defineWebSocketQueue](../../../config/webserver/web-socket-queue.md) — managed messaging layer that tracks connections for you.
+- [askCatch](../../../actions/core/system/ask-catch.md) — catch the throttled/disconnected errors above.

package/template/docusaurus/docs/actions/xstate/_category_.json

@@ -0,0 +1 @@
+{ "label": "quidproquo-xstate", "position": 3, "link": { "type": "generated-index", "description": "Action requesters for driving XState state machines from a story." } }

package/template/docusaurus/docs/actions/xstate/ask-state-machine-create.md

@@ -0,0 +1,60 @@
+---
+title: askStateMachineCreate
+description: Create and start a persistent instance of a defined state machine, seeded with your data.
+---
+
+# askStateMachineCreate
+
+Creates a new instance of a [state machine](../../config/xstate/state-machine.md), starts it at its initial state, and persists it under a given `id`. Use this to begin a durable workflow — an order, a subscription, an onboarding flow — that later stories will advance with [askStateMachineSendEvent](./ask-state-machine-send-event.md).
+
+- **Action type:** `StateMachineActionType.Create`
+- **On the runtime:** the processor builds the XState machine from your [defineStateMachine](../../config/xstate/state-machine.md) config, starts an actor, captures its **initial persisted snapshot**, merges `id` and that snapshot (under the machine's `stateField`, default `__machineState`) into your `item`, and upserts the whole record into the machine's backing key-value store. Any entry actions that fire on start run their mapped stories.
+
+```typescript
+import { askStateMachineCreate } from 'quidproquo-xstate';
+
+export function* startOrder(orderId: string, customerId: string) {
+  const order = yield* askStateMachineCreate('order', orderId, {
+    customerId,
+    total: 4200,
+  });
+
+  // order now includes id, your fields, and the initial machine snapshot
+  return order;
+}
+```
+
+## Signature
+
+```typescript
+function* askStateMachineCreate<T>(
+  stateMachineName: string,
+  id: string,
+  item: T,
+): AskResponse<T>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `stateMachineName` | `string` | Name of the machine to instantiate — must match a machine declared with [defineStateMachine](../../config/xstate/state-machine.md). |
+| `id` | `string` | The unique id for this instance. It becomes the partition key of the row in the backing key-value store and the id you pass to every later state-machine action for this instance. |
+| `item` | `T` | Your own instance data. It is stored alongside the machine snapshot; `id` and the snapshot field are added to it automatically. |
+
+## Returns
+
+`T` — the persisted entity: your `item`, plus an `id` property and the initial persisted XState snapshot under the machine's `stateField` (default `__machineState`). Read the human-readable current state with [askStateMachineGetState](./ask-state-machine-get-state.md) rather than parsing the snapshot yourself.
+
+## Notes
+
+- The instance starts at the machine's `initial` state. Entry actions declared on that state fire immediately, running their mapped stories with the new entity as the argument.
+- Persistence rides on the machine's key-value store, so creating an instance is durable — it can be fetched and advanced by any later invocation.
+- If no machine with `stateMachineName` exists in the deployed config, the action fails with `ErrorTypeEnum.NotFound`. Wrap the call in [askCatch](../core/system/ask-catch.md) if you want to handle that in-story.
+
+## Related
+
+- [defineStateMachine](../../config/xstate/state-machine.md) — declares the machine this instance is created from.
+- [askStateMachineSendEvent](./ask-state-machine-send-event.md) — advance the instance by sending it an event.
+- [askStateMachineGetState](./ask-state-machine-get-state.md) — read the instance's current state.
+- [askStateMachineGet](./ask-state-machine-get.md) — fetch the full instance entity.

package/template/docusaurus/docs/actions/xstate/ask-state-machine-get-state.md

@@ -0,0 +1,65 @@
+---
+title: askStateMachineGetState
+description: Read the current state value of a state-machine instance and whether it has reached a final state.
+---
+
+# askStateMachineGetState
+
+Reads the current state of a [state-machine](../../config/xstate/state-machine.md) instance — the state name and whether the machine has finished. This is the lightweight way to ask "what state is this instance in?" without pulling the raw snapshot.
+
+- **Action type:** `StateMachineActionType.GetState`
+- **On the runtime:** the processor loads the instance from the machine's backing key-value store, rehydrates an XState actor from the persisted snapshot (under the machine's `stateField`), reads the actor's current snapshot, and returns its state value and status. String state values are returned as-is; nested/parallel state values are JSON-stringified.
+
+```typescript
+import { askStateMachineGetState } from 'quidproquo-xstate';
+
+export function* isOrderShipped(orderId: string) {
+  const state = yield* askStateMachineGetState('order', orderId);
+
+  if (state.done) {
+    return `Order finished in state: ${state.value}`;
+  }
+
+  return `Order is currently: ${state.value}`;
+}
+```
+
+## Signature
+
+```typescript
+function* askStateMachineGetState(
+  stateMachineName: string,
+  id: string,
+): AskResponse<StateMachineStateInfo>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `stateMachineName` | `string` | Name of the machine — must match a machine declared with [defineStateMachine](../../config/xstate/state-machine.md). |
+| `id` | `string` | The id of the instance to read. |
+
+## Returns
+
+`StateMachineStateInfo` — the current state of the instance.
+
+```typescript
+interface StateMachineStateInfo {
+  value: string;   // the current state name (nested/parallel values are JSON-stringified)
+  done: boolean;   // true once the machine has reached a final state
+}
+```
+
+## Notes
+
+- `done` is `true` when the XState actor's status is `'done'` — i.e. the machine has reached a `type: 'final'` state.
+- Unlike [askStateMachineGet](./ask-state-machine-get.md), this action rehydrates the machine, so it reflects the actual computed state rather than the raw stored snapshot.
+- Fails with `ErrorTypeEnum.NotFound` if the machine name is unknown, the instance does not exist, or the instance has no persisted snapshot on its `stateField`.
+
+## Related
+
+- [defineStateMachine](../../config/xstate/state-machine.md) — declares the machine and its states.
+- [askStateMachineSendEvent](./ask-state-machine-send-event.md) — drive a transition that changes this state.
+- [askStateMachineGet](./ask-state-machine-get.md) — fetch the full entity instead of just the state.
+- [askStateMachineCreate](./ask-state-machine-create.md) — create the instance.

package/template/docusaurus/docs/actions/xstate/ask-state-machine-get.md

@@ -0,0 +1,57 @@
+---
+title: askStateMachineGet
+description: Fetch the full persisted entity of a state-machine instance by id.
+---
+
+# askStateMachineGet
+
+Fetches a [state-machine](../../config/xstate/state-machine.md) instance by its `id` and returns the whole persisted entity — your own data plus the stored machine snapshot. Use this when you need the instance's data fields; to read just the current state name, prefer [askStateMachineGetState](./ask-state-machine-get-state.md).
+
+- **Action type:** `StateMachineActionType.Get`
+- **On the runtime:** the processor reads the row keyed by `id` from the machine's backing key-value store and returns it verbatim. It does not rehydrate the XState actor, so the machine's `stateField` still holds the raw persisted snapshot.
+
+```typescript
+import { askStateMachineGet } from 'quidproquo-xstate';
+
+interface Order {
+  id: string;
+  customerId: string;
+  total: number;
+}
+
+export function* loadOrder(orderId: string) {
+  const order = yield* askStateMachineGet<Order>('order', orderId);
+  return order;
+}
+```
+
+## Signature
+
+```typescript
+function* askStateMachineGet<T>(
+  stateMachineName: string,
+  id: string,
+): AskResponse<T>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `stateMachineName` | `string` | Name of the machine — must match a machine declared with [defineStateMachine](../../config/xstate/state-machine.md). |
+| `id` | `string` | The id of the instance to fetch. |
+
+## Returns
+
+`T` — the persisted entity: the `item` you created it with, plus its `id` and the persisted XState snapshot under the machine's `stateField` (default `__machineState`). To interpret the snapshot as a state name, call [askStateMachineGetState](./ask-state-machine-get-state.md).
+
+## Notes
+
+- Fails with `ErrorTypeEnum.NotFound` if the machine name is unknown, or if no instance with that `id` exists. Use [askCatch](../core/system/ask-catch.md) to handle a missing instance in-story.
+
+## Related
+
+- [defineStateMachine](../../config/xstate/state-machine.md) — declares the machine and its backing store.
+- [askStateMachineGetState](./ask-state-machine-get-state.md) — read the current state name/done flag instead of the raw entity.
+- [askStateMachineCreate](./ask-state-machine-create.md) — create the instance in the first place.
+- [askStateMachineSendEvent](./ask-state-machine-send-event.md) — advance the instance.

package/template/docusaurus/docs/actions/xstate/ask-state-machine-send-event.md

@@ -0,0 +1,69 @@
+---
+title: askStateMachineSendEvent
+description: Send an event to a state-machine instance to drive a transition, run its guards and actions, and persist the new state.
+---
+
+# askStateMachineSendEvent
+
+Sends an event to a [state-machine](../../config/xstate/state-machine.md) instance, driving a transition. The runtime rehydrates the instance, evaluates its guards, applies the event, runs any side-effect actions, and persists the new state. This is how a durable workflow moves forward over time.
+
+- **Action type:** `StateMachineActionType.SendEvent`
+- **On the runtime:** the processor loads the instance from the backing key-value store, runs **every** configured guard story with `(entity, event)` to resolve each guard to a boolean, rehydrates the XState actor from the persisted snapshot, sends the event, and captures the new snapshot. If the event did not change state (and the machine is not done), it fails; otherwise it persists the new snapshot and runs the stories mapped to any actions that fired during the transition, passing `(entity, event)`.
+
+```typescript
+import { askStateMachineSendEvent } from 'quidproquo-xstate';
+
+export function* payOrder(orderId: string, paymentRef: string) {
+  const order = yield* askStateMachineSendEvent('order', orderId, {
+    type: 'PAY',
+    paymentRef,
+  });
+
+  return order; // the updated, re-persisted entity
+}
+```
+
+## Signature
+
+```typescript
+function* askStateMachineSendEvent<T>(
+  stateMachineName: string,
+  id: string,
+  event: StateMachineEvent,
+): AskResponse<T>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `stateMachineName` | `string` | Name of the machine — must match a machine declared with [defineStateMachine](../../config/xstate/state-machine.md). |
+| `id` | `string` | The id of the instance to advance. |
+| `event` | `StateMachineEvent` | The event to send. Its `type` selects the transition; any extra fields are payload passed through to guard and action stories. |
+
+### `StateMachineEvent`
+
+```typescript
+interface StateMachineEvent {
+  type: string;       // the XState event name (e.g. 'PAY', 'CANCEL')
+  [key: string]: any; // optional payload available to guards and actions
+}
+```
+
+## Returns
+
+`T` — the updated, re-persisted entity, with the new machine snapshot stored under the machine's `stateField`. Read the resulting state name with [askStateMachineGetState](./ask-state-machine-get-state.md).
+
+## Notes
+
+- **Guards run first, and all of them.** Before the event is applied, every guard story configured on the machine is executed with `(entity, event)` and reduced to a boolean, then fed to XState. Keep guard stories side-effect-light.
+- **Actions run after the transition is persisted.** Each XState action that fires during the transition runs its mapped story with `(entity, event)`; a story error aborts the action with that error.
+- **Invalid events fail.** If the event produces no state change and the machine is not in a final state, the action fails with `ErrorTypeEnum.BadRequest` (`Event '<type>' is not valid for current state '<state>'`).
+- Fails with `ErrorTypeEnum.NotFound` if the machine name is unknown or the instance does not exist. Guard/action story errors and the persistence upsert error propagate with their own error types. Use [askCatch](../core/system/ask-catch.md) to handle these in-story.
+
+## Related
+
+- [defineStateMachine](../../config/xstate/state-machine.md) — declares the machine, its transitions, guards, and actions.
+- [askStateMachineGetState](./ask-state-machine-get-state.md) — read the state the event moved the instance into.
+- [askStateMachineCreate](./ask-state-machine-create.md) — create the instance before sending events.
+- [askStateMachineGet](./ask-state-machine-get.md) — fetch the full instance entity.

package/template/docusaurus/docs/api/index.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 1
+---
+
+# API Reference
+
+Complete API documentation for the quidproquo framework, split into two sections:
+
+## Config
+
+The `defineXYZ(...)` functions you compose into your service's QPQ config. Each one declares a piece of infrastructure or configuration — storage drives, queues, event buses, routes — that the deploy layer turns into real resources.
+
+## Action Requesters
+
+The `askXYZ(...)` generator functions your stories use to actually do things — read files, send messages, query users. Each page documents the function's parameters, return type, errors, and the config that controls it.
+
+Both sections are organised by package (`quidproquo-core`, `quidproquo-webserver`, ...), and within Action Requesters by action domain (File, Queue, EventBus, ...).