@opinionated-machine/sse-fallback 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,365 @@
+# @opinionated-machine/sse-fallback
+
+Browser-safe client core for **SSE with a transparent polling fallback**, built
+around `opinionated-machine` dual-mode contracts (one path serving JSON via
+`Accept: application/json` and SSE via `Accept: text/event-stream`).
+
+The client subscribes to the SSE branch for low-latency pushes and keeps a
+**deadman timer**: when no data event arrives within the window, it polls the
+JSON branch of the same route. A single **version gate** reconciles the two
+channels, so app code sees exactly one uniform event stream — whether an event
+was pushed, replayed after a reconnect, or synthesized from a poll snapshot is
+invisible.
+
+**One runtime dependency**, `@opinionated-machine/sse-parser`: the SSE
+wire-format parser, shared with the server framework's test helpers so both
+ends of a stream frame it identically. It is itself dependency-free and
+browser-safe. `zod` and `@lokalise/api-contracts` are type-only optional peers,
+and nothing from Node.js or Fastify is imported, so the package is safe to ship
+to browsers (enforced by a source-tree check in CI).
+
+## Why
+
+Push channels fail silently: connections die without an error event, proxies
+kill idle streams, a room rebalance drops a message. When the missed
+notification gates workflow progress ("upload finished"), the user is stuck.
+This package makes **polling the correctness backbone** (bounded staleness,
+guaranteed) and SSE the latency optimization — instead of the other way
+around.
+
+Two failure detectors run independently:
+
+| Timer | Reset by | Catches |
+|---|---|---|
+| `staleConnection` | **any bytes** (incl. `: heartbeat` comments) | silently dead connections — force-close + reconnect + poll |
+| `deadman` | **delivered events only** | healthy-but-wrong streams: a dropped message on a live connection, repaired by a reconciliation poll |
+
+Heartbeats deliberately do *not* reset the deadman, and neither does a
+duplicate the version gate drops: transport liveness is not delivery
+correctness. A delivered event pushes the next poll out but does not shorten
+the interval back to `deadmanDelayMs`; a stream that keeps delivering needs
+less reconciliation, so only a poll that finds news the stream missed resets
+the backoff.
+
+## Declaring a binding
+
+The binding is the one thing that cannot be inferred: how a poll snapshot
+relates to the SSE events. Declare it once, colocated with the contract:
+
+```ts
+import { defineFallbackBinding } from '@opinionated-machine/sse-fallback'
+
+// Use case A — await async completion
+export const uploadStatusBinding = defineFallbackBinding(uploadStatusContract, {
+  // Translate a snapshot into events; [] = "no news" (still advances the watermark)
+  snapshotToEvents: (s) =>
+    s.status === 'completed'
+      ? [{ event: 'uploadFinished', data: { result: s.result } }]
+      : s.status === 'failed'
+        ? [{ event: 'uploadFailed', data: { error: s.error } }]
+        : [],
+  version: { ofSnapshot: (s) => s.version },
+  terminalEvents: ['uploadFinished', 'uploadFailed'],
+})
+
+// Use case B — initial state load + live hydration
+export const projectStateBinding = defineFallbackBinding(projectStateContract, {
+  snapshotEvent: 'stateChanged', // shorthand: snapshot body ≡ this event's payload
+  version: { ofSnapshot: (s) => s.revision, ofEvent: (e) => e.data.revision, dense: true },
+  state: {
+    init: (s) => s,
+    apply: (state, e) => applyDelta(state, e),
+  },
+})
+```
+
+Escape hatches: `bindFallbackContracts(pollContract, streamContract, config)`
+binds two pre-existing contracts on different paths;
+`fromLegacyDualModeContract(contract, config)` accepts legacy
+`buildSseContract` dual-mode contracts.
+
+## Subscribing
+
+```ts
+import { createResilientSubscription } from '@opinionated-machine/sse-fallback'
+
+const sub = createResilientSubscription(uploadStatusBinding, {
+  transport,                       // FallbackTransport (see below)
+  params: { pathParams: { uploadId } },
+})
+
+// Use case A: identical result whether it traveled over SSE or a poll
+const { result } = await sub.waitFor('uploadFinished')
+
+// Or consume the uniform stream
+for await (const event of sub.events()) { ... }
+
+// Use case B: reduced state
+sub.onStateChange((state) => render(state))
+
+sub.status                        // 'connecting' | 'live' | 'reconnecting' | 'polling' | 'stopped'
+sub.nudge()                       // force an immediate reconciliation poll
+sub.stop()
+```
+
+### Why it stopped
+
+`'stopped'` alone cannot be acted on: a completed job, an expired session and
+a caller's own `stop()` all land there. Every stop carries a reason:
+
+```ts
+sub.onStop(({ reason, status, limit }) => { ... })
+sub.onStatusChange((status, detail) => { ... })   // detail is set for 'stopped'
+sub.result                                        // undefined while running
+
+try {
+  await sub.waitFor('uploadFinished')
+} catch (error) {
+  if (error instanceof SubscriptionStoppedError && error.reason === 'budget-exhausted') {
+    showRetryPrompt()
+  }
+}
+```
+
+| `reason` | Meaning |
+|---|---|
+| `'terminal-event'` | a terminal event was delivered — success |
+| `'unretryable-status'` | refused with a status in `unretryableStatuses` (`status`, `channel`) |
+| `'budget-exhausted'` | `subscriptionBudget` ran out (`limit`) — show an error and offer a retry |
+| `'manual'` | the caller called `stop()`, or the creation `signal` aborted |
+
+### Bounding a pending operation
+
+Every individual wait is bounded, but the subscription as a whole is not: a
+backend stuck in a pending state deadman-polls until the tab closes. For
+pending-completion subscriptions, declare a ceiling:
+
+```ts
+createResilientSubscription(binding, {
+  transport,
+  policy: { subscriptionBudget: { maxDurationMs: 10 * 60_000, maxPolls: 200 } },
+})
+```
+
+Unset by default, so a live-state surface keeps running for as long as it is
+open.
+
+### Recovering from an expired token
+
+A 401 in a SPA is usually an expired token rather than a genuinely
+unauthorized caller, and recovering without a page reload is the point of this
+package. Give it a way to refresh:
+
+```ts
+createResilientSubscription(binding, {
+  transport,
+  onAuthChallenge: async () => {
+    await auth.refresh()        // the transport builds each request fresh
+    return true                 // retry the refused poll/connect once
+  },
+})
+```
+
+The retry is granted once per failure streak: a second refusal with no
+successful request in between stops the subscription with
+`'unretryable-status'`.
+
+### Adopting before the SSE endpoint exists
+
+`policy.mode: 'poll-only'` (or the `POLL_ONLY_POLICY` preset) never opens a
+stream. The binding, version gate, reconciler and state machine are the same
+ones the streaming rollout will use, so enabling SSE later is a config change
+on an already-integrated subscription rather than a second migration.
+
+The state machine: `CONNECTING → HYDRATING → LIVE ⇄ RECONNECTING →
+POLLING_ONLY → STOPPED`. Hydration is **subscribe-first**: the stream opens,
+live events are buffered, the snapshot is fetched, then buffered events newer
+than the snapshot are flushed — a zero missed-event window. After N
+consecutive connect failures the subscription degrades to pure polling and
+keeps probing SSE in the background.
+
+## The version gate
+
+Every event and snapshot carries a version; an item is delivered iff its
+version exceeds the high-watermark. This one rule handles:
+
+- **duplicates** — an SSE event followed by a poll snapshot of the same update,
+- **the stale-poll race** — a slow poll response arriving *after* a newer
+  pushed event is dropped at arrival time,
+- **replay overlap** — server-side `Last-Event-ID` replay after reconnects.
+
+`version: 'none'` opts into at-least-once/last-writer-wins semantics as an
+adoption bridge — strongly prefer real versions.
+
+## Server-side guarantees (the adopting team's checklist)
+
+1. **Required**: a monotonic version per subscription scope, present in both
+   the snapshot body and each event; truthful (a snapshot at version *v*
+   reflects every event ≤ *v*). Snapshots must **subsume** prior events.
+2. **Recommended**: stamp the SSE `id:` with that version — the client's
+   default extraction (bare integers and `createEventIdSequence()` ids alike)
+   and `Last-Event-ID` replay then compose for free. Prefer a domain version
+   (`job.version`, a revision column) as the id source: it is per-scope and
+   writer-independent. A per-process `createEventIdSequence()` is safe only for
+   a single writer — two pods sequencing into the same room use different
+   epochs, so every alternation between them reads as an epoch change and costs
+   a resync poll. For multi-writer scopes use a domain version or the
+   Redis-backed
+   `createRedisEventIdSequence()` from
+   `@opinionated-machine/sse-rooms-redis`.
+3. Optional: dense versions (enables gap detection → instant repair polls),
+   `onReconnect` replay (declare `replay: 'trusted'` to skip post-reconnect
+   polls), heartbeats every ~15s (fast stale detection; correctness holds
+   without them).
+
+## Transport
+
+The core owns no HTTP. Implement two functions:
+
+```ts
+const transport: FallbackTransport = {
+  fetchSnapshot(request, { signal }) { ... },      // Accept: application/json
+  openStream(request, { signal, lastEventId }) { ... }, // Accept: text/event-stream,
+                                                   // yields decoded text chunks
+}
+```
+
+`openStream` should yield **raw text chunks** — the core parses SSE framing
+itself and uses chunk arrival as byte-level liveness, so heartbeat comments
+count without any transport logic. A scripted `TestTransport` ships in the
+package for deterministic fake-timer tests.
+
+### Wrapping a client that only exposes parsed events
+
+`EventSource` cannot expose comment frames at all, and an HTTP client whose
+SSE mode yields events rather than text has already dropped them. `openStream`
+may resolve with an `events: AsyncIterable<ParsedSseFrame>` instead of
+`chunks`:
+
+```ts
+openStream(request, { signal, lastEventId }) {
+  return { status: 200, headers, events: client.stream(request) }
+}
+```
+
+The cost is liveness, not correctness: `staleConnectionTimeoutMs` degrades
+from byte-level to EVENT-level, so a stream carrying only heartbeat *comments*
+looks idle and is force-closed at the timeout, and a silently dead connection
+is only noticed once it elapses. Heartbeat *events* (a named event rather than
+a comment) still reset it, and the deadman poll is unaffected. Prefer raw
+chunks where the client allows it.
+
+### Capping polls across subscriptions
+
+Each subscription jitters its own backoff, which says nothing about the others
+in the same tab: after a server blip every live subscription reconnects and
+fires its own reconciliation poll at once. An app running dozens of
+subscriptions turns one outage into a burst of dozens of requests against one
+origin.
+
+Share a gate between the subscriptions that should be capped together —
+normally one per origin:
+
+```ts
+import { createPollGate } from '@opinionated-machine/sse-fallback'
+
+const pollGate = createPollGate({ maxConcurrent: 4, staggerMs: 2_000 })
+createResilientSubscription(binding, { transport, pollGate })
+```
+
+A gate delays polls, never cancels them: a subscription waiting for a slot
+keeps its in-flight latch, so its deadman does not stack a second poll behind
+the first. Without a gate, capping and staggering are the transport's
+responsibility.
+
+## Policy defaults
+
+| Setting | Default | Notes |
+|---|---|---|
+| `initialPoll` | `'eager'` | closes the startup race for one GET |
+| `deadmanDelayMs` | 10 000 | `LIVE_STATE_POLICY` preset: 120 000 |
+| `deadmanIdleBackoff` | ×1.5 up to 60 s | quiet subscriptions poll less; only a poll that finds news resets it |
+| `staleConnectionTimeoutMs` | 60 000 | `'off'` to disable byte-level liveness |
+| `connectTimeoutMs` | 15 000 | a connect that never sends headers is a failure, not a stall |
+| `pollTimeoutMs` | 10 000 | a poll that never settles would disable the backbone |
+| `pollFailureBackoff` / `sseRetryBackoff` | 1 s ×2 up to 30 s, full jitter | |
+| `serverRetryHintBounds` | 250 ms – 60 s | clamps the server's `retry:` hint |
+| `degradedAfterFailures` | 3 | then `POLLING_ONLY` |
+| `degradedPollIntervalMs` | 15 000 | the "old polling world", kept humane |
+| `hydrationBufferLimit` | 1 000 | overflow → drop buffer + refetch |
+| `hydrationAbandonAfterFailures` | 3 | flush the buffer rather than silence a healthy stream |
+| `unretryableStatuses` | 401, 403, 404 | stop instead of retrying |
+| `authChallengeStatuses` | 401 | offered to `onAuthChallenge` before giving up |
+| `mode` | `'dual'` | `'poll-only'` never opens a stream |
+| `subscriptionBudget` | unset | `{ maxDurationMs, maxPolls }` — a hard give-up bound |
+
+Every wait in the machine is bounded, because an unbounded one turns the
+fallback into no fallback at all: a hung connect or a poll that never settles
+would leave nothing armed, which is precisely the silent-failure class this
+package exists to catch.
+
+## Event ids and the version gate
+
+The default version extractor reads the SSE `id:` and accepts two shapes: a
+bare integer (`"42"`), and the `"<epoch>-<counter>"` ids produced by the
+server-side `createEventIdSequence()`. Sequence ids order by epoch first and
+then counter, so a process restart — a new, larger epoch with the counter back
+at 1 — reads as *newer*, not as a flood of duplicates.
+
+The epoch is a string of digits, which is what makes `<digits>-<digits>` an
+unambiguous marker for a generated id: a UUID matches `<anything>-<digits>` too,
+and reading a chunk of one as a counter would order events at random. The
+server-side generators refuse a non-numeric epoch for that reason, so every id
+they produce is one this extractor can order.
+
+An epoch change is a resynchronization point, not a measurable gap: the counters
+on either side are unrelated, so the reconciler reports it as a gap with
+`reason: 'epoch-change'`, polls for a snapshot, and rebuilds delta state from it
+rather than applying more deltas across the restart.
+
+That holds in **either direction**. A new epoch is not necessarily a larger one:
+moving a writer from `createEventIdSequence()` (epoch seeded from `Date.now()`)
+to `createRedisEventIdSequence()` (epoch `'0'` by default) lowers it. The epoch
+is compared before the duplicate gate for exactly that reason — ranking the new
+scope as "older" would drop every event and snapshot that followed it, forever.
+The new epoch simply becomes the ordering scope, and the resync poll repairs
+whatever the switch skipped. This applies to the default comparator only: a
+binding that declares `version.compare` owns ordering end to end, epochs
+included, and its verdict is never overridden.
+
+Ids in any other shape (a UUID, say) carry **no** version: they are unique but
+not orderable, so events are delivered at-least-once and the watermark does not
+move. Declare `version.ofEvent` explicitly for any other id scheme rather than
+letting an unorderable id masquerade as a version.
+
+The same rule protects the gate from a version it cannot order at all —
+`version.ofSnapshot` returning `undefined` because the body has no version
+field, or `NaN`, or an empty string. Such a value is never stored as the
+watermark (one that compares as "not less than" everything would drop the whole
+stream as duplicates); the item is delivered, the watermark stays put, and
+`diagnostics.onInvalidVersion` reports the degradation to at-least-once, which
+is otherwise invisible.
+
+## Known limitations (v1)
+
+- **Snapshots must subsume events.** Append-only feeds where every event
+  matters individually and the snapshot only shows the latest item don't fit —
+  expose a windowed snapshot (`{ items: [...], version }`) instead.
+- **One subscription is one physical SSE connection.** The binding model is
+  per-resource, so a tab with several pending jobs plus a live-state surface
+  opens one stream each. Under HTTP/1.1 that runs into the ~6-connections-per-
+  origin browser cap.
+
+  The position this package takes: per-resource streams are the recommended
+  model **behind an HTTP/2 gateway**, which removes the cap — the Envoy config
+  generated by `@opinionated-machine/gateway-envoy` in this repo is where that
+  is configured — and the per-scope snapshot/version model is what makes the
+  fallback correct in the first place. Where h2 cannot be relied on, stream
+  sharing is the roadmap item: either a SharedWorker `FallbackTransport`, or a
+  transport-level multiplexer where N logical subscriptions share one physical
+  stream keyed by contract + params, each keeping its own version gate.
+  `bindFallbackContracts` binds one poll to one stream today, so the
+  multiplexer is the missing piece for a user-wide stream.
+  `nudge()` / `stop()` give visibility-aware wrappers the hooks they need.
+- No reorder buffer: on a single TCP stream, gaps are losses, not reorders —
+  polling is the repair path.

package/dist/binding.d.ts

@@ -0,0 +1,82 @@
+import type { EventPayloadMap, FallbackBindingConfig, InferContractEvents, InferContractSnapshot, InferLegacyEvents, InferLegacySnapshot } from './bindingTypes.ts';
+import type { TransportRequest } from './transport.ts';
+/**
+ * Symbol under which a binding is stamped on its contract(s), so server-side
+ * tooling can later introspect bindings without a package dependency in
+ * either direction (`Symbol.for` — shared across duplicate package copies).
+ */
+export declare const FALLBACK_BINDING_SYMBOL: unique symbol;
+/** Request parameters supplied when subscribing. */
+export type FallbackRequestParams = {
+    pathParams?: Record<string, string | number>;
+    queryParams?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    /** Request body for payload (POST/PUT/PATCH) contracts. */
+    body?: unknown;
+};
+/**
+ * A normalized fallback binding: the client core's single input shape.
+ * Produced by {@link defineFallbackBinding} (dual-mode contract — the
+ * primary form) or {@link bindFallbackContracts} (two separate contracts —
+ * the escape hatch); both normalize to a snapshot-request builder + a
+ * stream-request builder + the reconciliation config.
+ */
+export type FallbackBinding<Snapshot = unknown, Events extends EventPayloadMap = EventPayloadMap, State = undefined> = {
+    readonly config: FallbackBindingConfig<Snapshot, Events, State>;
+    buildSnapshotRequest(params: FallbackRequestParams): TransportRequest;
+    buildStreamRequest(params: FallbackRequestParams): TransportRequest;
+};
+/** Read a binding previously stamped on a contract, or `undefined`. */
+export declare function readFallbackBinding(contract: object): FallbackBinding | undefined;
+/**
+ * Declare a fallback binding on a dual-mode `defineApiContract` contract —
+ * one path serving JSON (the poll) and SSE (the push) via Accept
+ * negotiation. Snapshot and event types are inferred from the contract.
+ *
+ * @example
+ * ```ts
+ * export const uploadStatusBinding = defineFallbackBinding(uploadStatusContract, {
+ *   snapshotToEvents: (s) =>
+ *     s.status === 'completed' ? [{ event: 'uploadFinished', data: { result: s.result } }] : [],
+ *   version: { ofSnapshot: (s) => s.version },
+ *   terminalEvents: ['uploadFinished', 'uploadFailed'],
+ * })
+ * ```
+ */
+export declare function defineFallbackBinding<TContract extends {
+    method: string;
+    pathResolver: (p: never) => string;
+}, Snapshot = InferContractSnapshot<TContract>, Events extends EventPayloadMap = InferContractEvents<TContract>, State = undefined>(contract: TContract, config: FallbackBindingConfig<NoInfer<Snapshot>, NoInfer<Events>, State>): FallbackBinding<Snapshot, Events, State>;
+export type BindFallbackContractsOptions<Snapshot, Events extends EventPayloadMap, State> = {
+    /**
+     * Map the subscription params onto each contract's params when their
+     * request shapes differ. Defaults to passing params through unchanged.
+     */
+    mapParams?: {
+        toSnapshot?: (params: FallbackRequestParams) => FallbackRequestParams;
+        toStream?: (params: FallbackRequestParams) => FallbackRequestParams;
+    };
+} & FallbackBindingConfig<Snapshot, Events, State>;
+/**
+ * Escape hatch: bind two PRE-EXISTING contracts — a plain REST contract (the
+ * poll) and an SSE contract (the push) on different paths. Prefer the
+ * single dual-mode contract form (`defineFallbackBinding`) for new
+ * endpoints: one contract cannot drift against itself.
+ */
+export declare function bindFallbackContracts<TPoll extends {
+    method: string;
+    pathResolver: (p: never) => string;
+}, TStream extends {
+    method: string;
+    pathResolver: (p: never) => string;
+}, Snapshot = InferContractSnapshot<TPoll>, Events extends EventPayloadMap = [InferContractEvents<TStream>] extends [never] ? InferLegacyEvents<TStream> : InferContractEvents<TStream>, State = undefined>(poll: TPoll, stream: TStream, options: BindFallbackContractsOptions<NoInfer<Snapshot>, NoInfer<Events>, State>): FallbackBinding<Snapshot, Events, State>;
+/**
+ * Declare a fallback binding on a legacy `buildSseContract` dual-mode
+ * contract (`successResponseBodySchema` + `serverSentEventSchemas`).
+ */
+export declare function fromLegacyDualModeContract<TContract extends {
+    method: string;
+    pathResolver: (p: never) => string;
+    isDualMode: boolean;
+}, Snapshot = InferLegacySnapshot<TContract>, Events extends EventPayloadMap = InferLegacyEvents<TContract>, State = undefined>(contract: TContract, config: FallbackBindingConfig<NoInfer<Snapshot>, NoInfer<Events>, State>): FallbackBinding<Snapshot, Events, State>;
+//# sourceMappingURL=binding.d.ts.map

package/dist/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"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"}

package/dist/binding.js

@@ -0,0 +1,181 @@
+/**
+ * Symbol under which a binding is stamped on its contract(s), so server-side
+ * tooling can later introspect bindings without a package dependency in
+ * either direction (`Symbol.for` — shared across duplicate package copies).
+ */
+export const FALLBACK_BINDING_SYMBOL = Symbol.for('opinionated-machine.sse-fallback.binding');
+const SUCCESS_STATUS_CODES = [200, 201, 202, 203, 206, 207, 208, 226];
+function isSseBodyDescriptor(value) {
+    return (typeof value === 'object' && value !== null && value._tag === 'SseBody');
+}
+function inspectResponseEntry(entry, shape) {
+    const content = entry.content;
+    if (!content || typeof content !== 'object') {
+        // A bare schema entry is a JSON response.
+        shape.hasNonSse = true;
+        return;
+    }
+    for (const descriptor of Object.values(content)) {
+        if (isSseBodyDescriptor(descriptor))
+            shape.hasSse = true;
+        else
+            shape.hasNonSse = true;
+    }
+    if (entry.allowNoBody)
+        shape.hasNonSse = true;
+}
+function inspectApiContractResponses(contract) {
+    const shape = { hasSse: false, hasNonSse: false };
+    for (const code of SUCCESS_STATUS_CODES) {
+        const entry = contract.responsesByStatusCode?.[String(code)];
+        if (entry !== undefined) {
+            inspectResponseEntry(entry, shape);
+        }
+    }
+    return shape;
+}
+function validateConfig(config) {
+    const hasMapper = config.snapshotToEvents !== undefined;
+    const hasShorthand = config.snapshotEvent !== undefined;
+    if (hasMapper === hasShorthand) {
+        throw new Error('FallbackBindingConfig requires exactly one of snapshotToEvents / snapshotEvent.');
+    }
+}
+/** Expand the `snapshotEvent` shorthand into `snapshotToEvents`. */
+function normalizeConfig(config) {
+    validateConfig(config);
+    if (config.snapshotEvent === undefined)
+        return config;
+    const eventName = config.snapshotEvent;
+    return {
+        ...config,
+        snapshotToEvents: (snapshot) => [
+            { event: eventName, data: snapshot },
+        ],
+    };
+}
+function stringifyQuery(queryParams) {
+    if (!queryParams)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(queryParams)) {
+        if (value === undefined)
+            continue;
+        out[key] = String(value);
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function buildRequest(contract, params) {
+    return {
+        path: contract.pathResolver(params.pathParams ?? {}),
+        method: contract.method,
+        ...(stringifyQuery(params.queryParams) ? { query: stringifyQuery(params.queryParams) } : {}),
+        ...(params.headers ? { headers: params.headers } : {}),
+        ...(params.body !== undefined ? { body: params.body } : {}),
+    };
+}
+function stampBinding(contract, binding) {
+    Object.defineProperty(contract, FALLBACK_BINDING_SYMBOL, {
+        value: binding,
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
+}
+/** Read a binding previously stamped on a contract, or `undefined`. */
+export function readFallbackBinding(contract) {
+    return contract[FALLBACK_BINDING_SYMBOL];
+}
+// ============================================================================
+// Primary form: one dual-mode contract IS the binding
+// ============================================================================
+/**
+ * Declare a fallback binding on a dual-mode `defineApiContract` contract —
+ * one path serving JSON (the poll) and SSE (the push) via Accept
+ * negotiation. Snapshot and event types are inferred from the contract.
+ *
+ * @example
+ * ```ts
+ * export const uploadStatusBinding = defineFallbackBinding(uploadStatusContract, {
+ *   snapshotToEvents: (s) =>
+ *     s.status === 'completed' ? [{ event: 'uploadFinished', data: { result: s.result } }] : [],
+ *   version: { ofSnapshot: (s) => s.version },
+ *   terminalEvents: ['uploadFinished', 'uploadFailed'],
+ * })
+ * ```
+ */
+export function defineFallbackBinding(contract, 
+// NoInfer: Snapshot/Events come from the CONTRACT (via the defaults), never
+// widened from whatever the config functions happen to mention.
+config) {
+    const contractLike = contract;
+    const shape = inspectApiContractResponses(contractLike);
+    const isLegacyDual = contractLike.isDualMode === true;
+    if (!isLegacyDual && !(shape.hasSse && shape.hasNonSse)) {
+        throw new Error('defineFallbackBinding requires a dual-mode contract (a success response with both an SSE and a non-SSE representation). ' +
+            'For separate poll/stream contracts use bindFallbackContracts; for legacy dual-mode contracts use fromLegacyDualModeContract.');
+    }
+    const normalized = normalizeConfig(config);
+    const binding = {
+        config: normalized,
+        buildSnapshotRequest: (params) => buildRequest(contractLike, params),
+        buildStreamRequest: (params) => buildRequest(contractLike, params),
+    };
+    stampBinding(contract, binding);
+    return binding;
+}
+/**
+ * Escape hatch: bind two PRE-EXISTING contracts — a plain REST contract (the
+ * poll) and an SSE contract (the push) on different paths. Prefer the
+ * single dual-mode contract form (`defineFallbackBinding`) for new
+ * endpoints: one contract cannot drift against itself.
+ */
+export function bindFallbackContracts(poll, stream, options) {
+    const pollLike = poll;
+    const streamLike = stream;
+    const pollShape = inspectApiContractResponses(pollLike);
+    if (pollShape.hasSse) {
+        throw new Error('bindFallbackContracts: the poll contract must be a plain (non-SSE) contract — its SSE responses would never be used.');
+    }
+    const streamShape = inspectApiContractResponses(streamLike);
+    const streamIsLegacySse = streamLike.isSSE === true ||
+        streamLike.isDualMode === true ||
+        streamLike.serverSentEventSchemas !== undefined;
+    if (!streamShape.hasSse && !streamIsLegacySse) {
+        throw new Error('bindFallbackContracts: the stream contract must declare an SSE success response.');
+    }
+    const { mapParams, ...config } = options;
+    const normalized = normalizeConfig(config);
+    const toSnapshot = mapParams?.toSnapshot ?? ((params) => params);
+    const toStream = mapParams?.toStream ?? ((params) => params);
+    const binding = {
+        config: normalized,
+        buildSnapshotRequest: (params) => buildRequest(pollLike, toSnapshot(params)),
+        buildStreamRequest: (params) => buildRequest(streamLike, toStream(params)),
+    };
+    stampBinding(poll, binding);
+    stampBinding(stream, binding);
+    return binding;
+}
+// ============================================================================
+// Legacy adapter
+// ============================================================================
+/**
+ * Declare a fallback binding on a legacy `buildSseContract` dual-mode
+ * contract (`successResponseBodySchema` + `serverSentEventSchemas`).
+ */
+export function fromLegacyDualModeContract(contract, config) {
+    if (contract.isDualMode !== true) {
+        throw new Error('fromLegacyDualModeContract requires a legacy dual-mode contract (buildSseContract with successResponseBodySchema).');
+    }
+    const contractLike = contract;
+    const normalized = normalizeConfig(config);
+    const binding = {
+        config: normalized,
+        buildSnapshotRequest: (params) => buildRequest(contractLike, params),
+        buildStreamRequest: (params) => buildRequest(contractLike, params),
+    };
+    stampBinding(contract, binding);
+    return binding;
+}
+//# sourceMappingURL=binding.js.map

package/dist/binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"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"}