/** * vapor-chamber - Transports * * A transport is the work for the actions it covers: declared once at the * async bus (`createAsyncCommandBus({ transport })`), it sends a command to a * backend where a local handler would run it. Every plugin wraps it, the * bus's retry re-sends through it, and its answer is written there. */ import type { BaseBus, Transport } from './command-bus'; import { Accepted } from './accepted'; import { type Outbox } from './outbox'; import type { HttpClient } from './http'; import type { ProblemDetails } from './http-errors'; import type { Signal } from './signal'; export { Accepted }; /** * A command on every wire (docs/contract.md 4): `id` where * answers are multiplexed (a batch, a WebSocket), as on the answer side; `meta` * only with a fact a backend can use. Its HTTP metadata, the idempotency key, * is the `Idempotency-Key` header when the request is the command, and that * name in `headers` when the command is multiplexed (OData JSON 4.01 19.1). * Log s35.138, 36.47. */ export type CommandEnvelope = { id?: string; command: string; target: any; payload?: any; meta?: EnvelopeMeta; headers?: Record; }; /** The part of a command's meta that crosses the wire as the command's own data. */ export type EnvelopeMeta = { correlationId?: string; causationId?: string; }; /** * A command's answer, the same on every wire (docs/contract.md 4): * `state` on success, `redirect` for a navigation, `problem` on failure, * one of the three. A batched result and a WebSocket frame carry `id` beside * it; a single command's failure is its non-2xx response's body. */ export type BackendResponse = { state?: unknown; /** * Store states the server declares beside a success, by store id: each * store with that id on the bus takes its state, whatever the command was * (docs/store.md, A store behind a transport). Log s35.186. */ stores?: Record; /** A navigation the backend hands back instead of a result - see `onRedirect`. */ redirect?: string; problem?: ProblemDetails; }; /** * An app's own transport: `send` answers the command, and `local()` runs the * action's local handler (or the missing-handler outcome), its fallback. A * throw or a rejection fails the dispatch as `transport:failed:send`. A send * that calls `local()` declares `localFallback: true`: only then may its * actions have a handler, `optimistic` aside * (tests/register-shadow-check.test.ts). * * @example * const offlineFirst = defineTransport((cmd, local) => (navigator.onLine ? send(cmd) : local()), { localFallback: true }) * const bus = createAsyncCommandBus({ transport: offlineFirst }) */ export declare function defineTransport(send: Transport['send'], options?: { localFallback?: boolean; }): Transport; export type HttpTransportOptions = { /** Backend endpoint URL (e.g. '/api/vc') */ endpoint: string; /** * CSRF token strategy: * - `false` (default) - don't attach any CSRF token * - `true` - read from DOM (meta tag, cookie, hidden input) and attach * as the appropriate header. Works with any server-rendered framework * that exposes a token via one of those three sources - Laravel Blade, * Rails, Django, .NET MVC, custom stacks. Auto-refreshes on HTTP 419. * An Inertia app on Laravel uses `true` too: with no meta tag it reads * the XSRF-TOKEN cookie Laravel sets. The transport makes its own requests, * which no Axios interceptor of the app touches. */ csrf?: boolean; /** * URL to fetch on a CSRF-expiry response (HTTP 419) to obtain a fresh * token. The default targets the Laravel Sanctum SPA convention because * it's the most common 419-issuing backend; override for other frameworks * or set to '' to disable the refresh fetch. * Default: '/sanctum/csrf-cookie'. */ csrfCookieUrl?: string; /** Additional headers merged into every request. A name matches in any case: its first spelling is kept and the last value wins (the Fetch Standard's "set"), so it goes out once. */ headers?: Record; /** Request timeout in ms. Default: 10_000 */ timeout?: number; /** External AbortSignal (e.g. tied to component lifecycle) */ signal?: AbortSignal; /** * Called when a 401 session-expired response is received. * A `session-expired` CustomEvent is also dispatched on `window`. */ onSessionExpired?: (status: number) => void; /** * Called when the backend answers with a `{ redirect: '/path' }` field in * its JSON body. Useful for handing a navigation to Inertia's router so a * vapor-chamber dispatch can move the page: * * onRedirect: (url) => router.visit(url) * * Either way the command fails as `transport:refused:redirect`, the url in * `error.context.url`. * * BODY FIELD ONLY, never a 3xx with `Location`: `fetch` defaults to * `redirect: 'follow'`, so the platform resolves a 3xx and hands the transport * the FINAL response. A backend * that wants this hook must say so in the body. Pinned by * `tests/transports-coverage.test.ts` ("does not call onRedirect for a * redirect STATUS without a body field"). */ onRedirect?: (url: string) => void; /** * Coalesce the commands sent within a window into one POST * (`{ commands: [...] }` answered by `{ results: [...] }`). Absent: one * request per command. */ batch?: HttpBatchOptions; /** * Abort controller whose signal cancels all in-flight requests when the * owning scope/component is disposed. In Vapor components, create an * AbortController in setup and pass it here - call `.abort()` in * onScopeDispose to cancel orphaned requests automatically. * * @example * // In