@voltro/client 0.56.0 → 0.58.0

package/dist/index.d.ts

@@ -574,9 +574,20 @@ export declare type ClientDescriptorMap = Readonly<Record<string, ClientDescript
 export declare interface ClientErrorEvent {
     /** The thrown value (Error | anything). */
     readonly error: unknown;
-    /** Where it came from. `route` = caught by the framework's route
-     *  ErrorBoundary (render OR loader); `manual` = app called a capture helper. */
-    readonly source: 'route' | 'manual';
+    /**
+     * Where it came from.
+     *
+     * `route` — caught by the framework's route ErrorBoundary (render OR loader).
+     * `manual` — app called a capture helper.
+     * `rpc.*` — a call that failed in the CLIENT, forwarded from the rpc error
+     * bus. Kept as three separate labels rather than one `rpc`, because they are
+     * different incidents to whoever reads the report: a failed mutation is a
+     * write the user watched fail, while a failed subscription is a screen that
+     * silently never filled — `data: undefined`, `loading: false`, an empty list
+     * that reads as "there is nothing here". Collapsing them makes the second
+     * unfindable, and the second is the expensive one.
+     */
+    readonly source: 'route' | 'manual' | 'rpc.mutation' | 'rpc.action' | 'rpc.subscription';
     /** React component stack, when the route boundary caught a render error. */
     readonly componentStack?: string;
     /** Active pathname at the time, for context. */
@@ -960,6 +971,15 @@ export declare interface EventValidation {
     readonly errors: Readonly<Record<string, string>>;
 }
 
+/** One currently-failing tag. */
+export declare interface FailedCall {
+    readonly tag: string;
+    readonly source: 'mutation' | 'action' | 'subscription';
+    readonly error: unknown;
+    /** When it failed, so a UI can say "since 12:04" rather than only "broken". */
+    readonly at: number;
+}
+
 export declare interface FieldDescriptor {
     /** Property name on the input object. */
     readonly name: string;
@@ -2077,7 +2097,17 @@ export declare interface ResumableAgentStreamState<E> {
     /** The UNWRAPPED inner events received so far, in order (deduped by seq). */
     readonly events: ReadonlyArray<E>;
     readonly status: ResumableStreamStatus;
-    /** How many times the transport dropped + auto-reconnected this run. */
+    /**
+     * How many times the transport dropped + auto-reconnected this run — the
+     * RUN TOTAL, which is NOT the number `maxReconnects` bounds.
+     *
+     * `maxReconnects` is a ceiling on CONSECUTIVE reconnects that made no
+     * progress, and the counter behind it resets whenever a reconnect delivers an
+     * event. So this total can exceed it on a long, healthy stream, and rendering
+     * "attempt {reconnects} of {maxReconnects}" puts `5/2` on the screen — which
+     * is what a deployment saw. The two names sit next to each other and read as a
+     * pair; they are not one, and there is no third field that is.
+     */
     readonly reconnects: number;
     /** Set when status === 'error'. */
     readonly error: unknown | undefined;
@@ -2480,10 +2510,50 @@ export declare class RpcErrorBus {
     on(listener: RpcErrorListener): () => void;
     /** Emit. Pipeline code (useMutation / subscriptionCache) calls this. */
     emit(event: RpcError): void;
+    /**
+     * Subscribe to SUCCESSES — the channel that makes a consecutive-failure
+     * ceiling mean what it says.
+     *
+     * ── Why the bus grew a second channel ──────────────────────────────────
+     *
+     * `wireAuthRefresh` bounds how often it may rebuild the transport on
+     * `Unauthenticated`, and `maxConsecutive` bounds the TOTAL — after that many
+     * refreshes *with no successful call in between*, it stops and leaves the
+     * error to the app, because at that point the credential is not stale, it is
+     * refused. "With no successful call in between" was carried by
+     * `AuthRefreshHandle.noteSuccess()`, a method the HOST had to remember to
+     * call, and the only host never called it.
+     *
+     * What that turns the ceiling into is the part worth writing down: not a
+     * loop, but a LIFETIME budget. A tab that rotates its token three times over
+     * a few hours exhausts it and then never refreshes again for as long as it
+     * stays open — every later expiry rejects every subscription it opens, each
+     * rejected entry is terminal for its transport, and the screen waits on a
+     * spinner that has nothing left to wait for.
+     *
+     * A host that must remember something will eventually not, which is the
+     * shape this repo keeps meeting. So the signal comes from the pipeline that
+     * already knows — the same one that emits the errors — and no host has to
+     * wire anything. `noteSuccess()` stays for a host with a better signal of its
+     * own; it is no longer what the policy depends on.
+     */
+    onSuccess(listener: RpcSuccessListener): () => void;
+    /** Emit a success. Called by the same pipeline code that calls `emit`. */
+    emitSuccess(event: RpcSuccess): void;
 }
 
 export declare type RpcErrorListener = (event: RpcError) => void;
 
+/** A call that SUCCEEDED. Carries only its source and tag — there is no payload
+ *  here on purpose: this channel exists so cross-cutting policy can tell
+ *  "working again" from "still broken", not so listeners can read data. */
+export declare interface RpcSuccess {
+    readonly source: 'mutation' | 'action' | 'subscription';
+    readonly tag: string;
+}
+
+export declare type RpcSuccessListener = (event: RpcSuccess) => void;
+
 /**
  * Run a sequence. Resolves with a discriminated result rather than rejecting —
  * the same "handled" semantics `useMutation`/`useAction` use, so the call site
@@ -3243,6 +3313,14 @@ export declare interface SubscriptionFailed extends SubscriptionMeta {
     readonly error: unknown;
 }
 
+export declare interface SubscriptionHealth {
+    /** Every tag whose last outcome on this api was a failure, newest first. */
+    readonly failed: ReadonlyArray<FailedCall>;
+    /** `false` as soon as anything is failing — the positive form, so a component
+     *  reads `if (!healthy)` instead of `if (failed.length > 0)`. */
+    readonly healthy: boolean;
+}
+
 /**
  * Deliberately NOT subscribed — `skip: true`.
  *
@@ -3568,6 +3646,45 @@ export declare interface TrackingSpec<P = Record<string, unknown>> {
     readonly map: TrackingMap<P>;
 }
 
+/** Where the one operation is. `uploading` and `transcribing` are separate
+ *  because their progress means different things and only one of them is
+ *  measurable. */
+export declare type TranscriptionPhase = 'idle' | 'uploading' | 'transcribing' | 'done' | 'error';
+
+export declare interface TranscriptionSegmentView {
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+    readonly speaker?: string;
+}
+
+export declare interface TranscriptionState {
+    readonly phase: TranscriptionPhase;
+    /**
+     * Progress of the CURRENT phase, 0..1 — and `undefined` while transcribing.
+     *
+     * Not a single number across both. An upload that finishes puts a combined bar
+     * at 100% while the model has not started, and a bar that says finished is
+     * worse than no bar. `undefined` is what an indeterminate spinner is for.
+     */
+    readonly progress: number | undefined;
+    readonly result: TranscriptionView | undefined;
+    readonly error: unknown | undefined;
+    /** Upload the file, then transcribe it. Resolves the transcript. */
+    readonly transcribe: (file: File | Blob) => Promise<TranscriptionView>;
+    /** Abort an upload in flight and return to idle. A transcription already
+     *  handed to the server is NOT cancelled — say so rather than pretend. */
+    readonly cancel: () => void;
+    readonly reset: () => void;
+}
+
+export declare interface TranscriptionView {
+    readonly text: string;
+    readonly language?: string;
+    readonly durationSec?: number;
+    readonly segments?: ReadonlyArray<TranscriptionSegmentView>;
+}
+
 /**
  * Jump one instance to the state recorded at `index` — the devtools panel's
  * back/forward.
@@ -3740,6 +3857,13 @@ export declare type UploadStatus = 'idle' | 'uploading' | 'success' | 'error';
  *  `<PermissionProvider>`. The hook form of `decideAccess`. */
 export declare const useAccessDecision: (guards: ReadonlyArray<ManifestGuard> | undefined) => AccessDecision;
 
+/**
+ * Invoke a server `defineAction` procedure by tag. Unlike `useMutation`,
+ * an action has no optimistic / cache surface — it's a unary call whose
+ * effects (sends, captures, side-effecting writes the framework must NOT
+ * preview locally) only become visible when the server pushes a delta on
+ * an independent subscription.
+ */
 export declare const useAction: <Input = unknown, Output = unknown>(apiName: string, rpcTag: string) => ActionState<Input, Output>;
 
 export declare const useAgent: (apiName: string, rpcTag: string) => AgentControls;
@@ -3883,7 +4007,26 @@ export declare interface UseEventOptions {
     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 const useFormBinding: <Input extends Record<string, unknown> = Record<string, unknown>, Output = unknown>(apiName: string, 
+/**
+ * The mutation to submit to — a tag, or a FUNCTION of the current values.
+ *
+ * The function form exists for the case where the form decides which mutation
+ * it is: a calendar entry becomes a recurring SERIES the moment "repeats" is
+ * ticked, and the series mutation takes eleven more fields. Deriving the tag
+ * outside the binding is not available — the values belong to the binding and
+ * do not exist before it — and re-mounting with a different tag resets the
+ * engine, which throws away everything the user has typed.
+ *
+ * It does not: the engine is constructed once and never rebuilt, so the tag
+ * may change on any render and the values, touched state and errors all
+ * survive it. What changes with the tag is the SCHEMA the binding validates
+ * against, which is the point.
+ *
+ * On the first render there are no values yet, so the function is called with
+ * the seeded defaults — the same thing the user is looking at.
+ */
+mutationTag: string | ((values: Partial<Input>) => string), options: UseFormBindingOptions<Input>) => FormBinding<Input, Output>;
 
 /** The enclosing binding, if a {@link FormBindingProvider} is mounted. */
 export declare const useFormBindingContext: () => FormBinding<Record<string, unknown>, unknown> | undefined;
@@ -4178,6 +4321,19 @@ export declare function useSubscription<T = unknown>(apiName: string, rpcTag: st
     readonly skip?: boolean;
 }): SubscriptionState<T> | SubscriptionIdle;
 
+/**
+ * The api's currently-refused calls.
+ *
+ * A tag enters the list when a call for it fails and LEAVES it when a call for
+ * the same tag succeeds — keyed by tag rather than counted, because the
+ * question a screen asks is "is this working now", and two failures of one tag
+ * are one broken thing.
+ *
+ *     const { healthy, failed } = useSubscriptionHealth('app')
+ *     if (!healthy) return <Banner tags={failed.map((f) => f.tag)} />
+ */
+export declare const useSubscriptionHealth: (apiName: string) => SubscriptionHealth;
+
 /** The column shape a `<DataTable query=…>` will render — from the query's
  *  output Schema. */
 export declare const useTableSkeleton: (apiName: string, queryTag: string) => ReadonlyArray<FieldDescriptor>;
@@ -4190,6 +4346,20 @@ export declare const useTableSkeleton: (apiName: string, queryTag: string) => Re
  */
 export declare const useTracking: <P extends object>(spec: TrackingSpec<P>, props: P, sink: TrackingSink) => P;
 
+export declare const useTranscription: (apiName: string, options: UseTranscriptionOptions) => TranscriptionState;
+
+export declare interface UseTranscriptionOptions {
+    /**
+     * The action that transcribes an uploaded file.
+     *
+     * Named rather than assumed: the app declares it, guards it, and decides which
+     * model runs. Its input is `{ storageRef }` plus whatever `extra` is passed.
+     */
+    readonly action: string;
+    /** Extra input merged into every call — a language hint, a thread id. */
+    readonly extra?: Readonly<Record<string, unknown>>;
+}
+
 export declare const useUndo: (options: UseUndoOptions) => UndoControls;
 
 export declare const useUndoLog: (apiName: string, options?: {