@voltro/client 0.23.0 → 0.25.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { ClipboardEvent as ClipboardEvent_2 } from 'react';
 import { Context } from 'react';
 import { DragEvent as DragEvent_2 } from 'react';
 import { Effect } from 'effect';
+import { EventDescriptor as EventDescriptor_2 } from '@voltro/protocol';
 import { Fiber } from 'effect';
 import { ManagedRuntime } from 'effect';
 import { ReactNode } from 'react';
@@ -650,6 +651,27 @@ declare type EventMap<E extends ReadonlyArray<EventDescriptor<string, unknown>>>
     [D in E[number] as D['name']]: D extends EventDescriptor<string, infer A> ? A : never;
 };
 
+export declare interface EventMiss {
+    /** How many deliveries were lost. */
+    readonly count: number;
+    readonly reason: EventMissReason;
+}
+
+/** Why a subscriber lost deliveries. Both are PROVEN counts, never guesses. */
+export declare type EventMissReason = 'buffer' | 'resume';
+
+export declare interface EventState {
+    /** `idle` = not subscribed (null key or `skip`); `connecting` = attaching;
+     *  `live` = the server confirmed the subscription is attached. */
+    readonly status: EventStatus;
+    /** Total deliveries PROVEN lost on this subscription since it mounted. */
+    readonly missed: number;
+    /** The most recent loss, with its cause. */
+    readonly lastMiss: EventMiss | undefined;
+}
+
+export declare type EventStatus = 'idle' | 'connecting' | 'live';
+
 export declare interface EventValidation {
     readonly valid: boolean;
     /** `path` → message, empty when valid. */
@@ -733,6 +755,13 @@ export declare interface FrameworkRuntimesProviderProps {
     readonly children: ReactNode;
 }
 
+/** Browser-safe unique idempotency key: prefer `crypto.randomUUID`, fall back to
+ *  a timestamp+counter for a NON-secure context (a LAN-IP dev server over plain
+ *  http, where `crypto.randomUUID` is undefined). One key per mutate() call is
+ *  stable for that call's lifetime — so a transport-level resend of the SAME
+ *  in-flight request reuses it and the server dedupes. */
+export declare const freshIdempotencyKey: () => string;
+
 /** The registered notifier, if any. */
 export declare const getMutationNotifier: () => MutationNotifier | undefined;
 
@@ -791,6 +820,12 @@ export declare interface MutateOptions<Input, Output> {
         readonly success?: string | ((output: Output, input: Input) => string);
         readonly error?: string | ((error: unknown, input: Input) => string);
     };
+    /** Idempotency key for this call. Omitted → a fresh one is minted per call
+     *  (safe against transport-level resends). Pass a STABLE value (e.g. derived
+     *  from the form/order id) to dedupe higher-level retries too — a double-click
+     *  or an offline resend of the same logical action then runs exactly once.
+     *  Only takes effect when the server has `idempotency` configured. */
+    readonly idempotencyKey?: string;
 }
 
 export declare interface MutationBuilder<Input, Output> extends MutationState<Input, Output> {
@@ -2192,6 +2227,39 @@ export declare const useDebounced: <T>(value: T, ms?: number) => T;
  */
 export declare const useDerived: <S extends Record<string, unknown>, T>(sources: S, reducer: (sources: S) => T) => T;
 
+/**
+ * Subscribe to a declared event.
+ *
+ * ```tsx
+ * useEvent(gameStarted, arenaId ? { arenaId } : null, (payload) => {
+ *   scene.switchTo('running', payload.gameId)
+ * })
+ * ```
+ *
+ * `payload` is typed from the descriptor — a wrong field name is a `tsc` error
+ * at this call site, and the `key` must structurally match the descriptor's key
+ * schema, so a typo cannot produce a subscription that silently never fires.
+ */
+export declare function useEvent<Name extends string, Key extends Schema.Schema.Any, Payload extends Schema.Schema.Any>(descriptor: EventDescriptor_2<Name, Key, Payload>, key: Schema.Schema.Type<Key> | null, handler: (payload: Schema.Schema.Type<Payload>) => void, options?: UseEventOptions): EventState;
+
+export declare interface UseEventOptions {
+    /**
+     * Called when the server can PROVE deliveries were lost — a serial gap while
+     * you were slow to read, or a reconnect older than the server's buffer.
+     *
+     * This is the callback an app builds recovery on: refetch the authoritative
+     * state, re-run the scene, resync the display. It exists because silence is
+     * the one outcome nothing can be built on — a screen cannot tell "nothing
+     * happened" from "I missed the signal", and every comparable product answers
+     * that question by dropping quietly.
+     */
+    readonly onMissed?: (miss: EventMiss) => void;
+    /** Suspend the subscription without unmounting. Same meaning as
+     *  `useSubscription`'s `skip`; a `null` key does the same thing. */
+    readonly skip?: boolean;
+    readonly apiName?: string;
+}
+
 export declare const useFormBinding: <Input extends Record<string, unknown> = Record<string, unknown>, Output = unknown>(apiName: string, mutationTag: string, options: UseFormBindingOptions<Input>) => FormBinding<Input, Output>;
 
 export declare interface UseFormBindingOptions<Input> {
@@ -2495,6 +2563,11 @@ export declare interface WindowSpec {
     readonly bottomSpacer: number;
 }
 
+/** Attach a per-call `idempotency-key` header to an rpc call, MERGED over the
+ *  ambient headers (the auth headers seeded on the runtime) — never replacing
+ *  them. The server mutation funnel reads it to dedupe a retried mutation. */
+export declare const withIdempotencyKey: <A, E, R>(call: Effect.Effect<A, E, R>, key: string) => Effect.Effect<A, E, R>;
+
 export declare interface WorkflowClientMessages {
     readonly signals?: Readonly<Record<string, unknown>>;
     readonly updates?: Readonly<Record<string, {