@stridge/kit 0.1.0-alpha.30 → 0.1.0-alpha.32

package/dist/events/hooks/useStridgeEventBus.js

@@ -0,0 +1 @@
+"use client";import{StridgeEventsContext as e}from"../context.js";import{use as t,useMemo as n}from"react";function r(){let r=t(e);return n(()=>r?{subscribeToFlow:r.bus.subscribeToFlow,subscribeToFlowEvent:r.bus.subscribeToFlowEvent,subscribeToAll:r.bus.subscribeToAll,subscribeToEvent:r.bus.subscribeToEvent}:null,[r])}export{r as useStridgeEventBus};

package/dist/events/hooks/useStridgeEvents.d.ts

@@ -0,0 +1,6 @@
+import { StridgeEvent } from "../types/index.js";
+
+//#region src/events/hooks/useStridgeEvents.d.ts
+declare function useStridgeEvents(handler: (event: StridgeEvent) => void): void;
+//#endregion
+export { useStridgeEvents };

package/dist/events/hooks/useStridgeEvents.js

@@ -0,0 +1 @@
+"use client";import{StridgeEventsContext as e}from"../context.js";import{useStableHandler as t}from"./useStableHandler.js";import{use as n,useEffect as r}from"react";function i(i){let a=n(e),o=t(i);r(()=>{if(a)return a.bus.subscribeToAll(e=>o.current(e))},[a,o])}export{i as useStridgeEvents};

package/dist/events/hooks/useStridgeFlowEvent.d.ts

@@ -0,0 +1,8 @@
+import { FlowEvent } from "../types/index.js";
+
+//#region src/events/hooks/useStridgeFlowEvent.d.ts
+declare function useStridgeFlowEvent<TType extends FlowEvent["type"]>(type: TType, handler: (event: Extract<FlowEvent, {
+  type: TType;
+}>) => void): void;
+//#endregion
+export { useStridgeFlowEvent };

package/dist/events/hooks/useStridgeFlowEvent.js

@@ -0,0 +1 @@
+"use client";import{StridgeEventsContext as e}from"../context.js";import{useStableHandler as t}from"./useStableHandler.js";import{use as n,useEffect as r}from"react";function i(i,a){let o=n(e),s=t(a);r(()=>{if(o)return o.bus.subscribeToFlowEvent(i,e=>s.current(e))},[o,s,i])}export{i as useStridgeFlowEvent};

package/dist/events/hooks/useStridgeFlowEvents.d.ts

@@ -0,0 +1,6 @@
+import { FlowEvent } from "../types/index.js";
+
+//#region src/events/hooks/useStridgeFlowEvents.d.ts
+declare function useStridgeFlowEvents(handler: (event: FlowEvent) => void): void;
+//#endregion
+export { useStridgeFlowEvents };

package/dist/events/hooks/useStridgeFlowEvents.js

@@ -0,0 +1 @@
+"use client";import{StridgeEventsContext as e}from"../context.js";import{useStableHandler as t}from"./useStableHandler.js";import{use as n,useEffect as r}from"react";function i(i){let a=n(e),o=t(i);r(()=>{if(a)return a.bus.subscribeToFlow(e=>o.current(e))},[a,o])}export{i as useStridgeFlowEvents};

package/dist/events/index.d.ts

@@ -0,0 +1,14 @@
+import { FlowIdKey } from "./bus/flowIdRegistry.js";
+import { useCurrentFlowId } from "./hooks/useCurrentFlowId.js";
+import { FailureCode, FailurePayloadBase, StridgeEventBase, StridgeEventFlow, StridgeEventTier } from "./types/envelope.js";
+import { DepositAmountChangedEvent, DepositAmountSubmittedEvent, DepositAssetClickedEvent, DepositBackClickedEvent, DepositCancelPhase, DepositCancelledEvent, DepositClosedEvent, DepositConfirmClickedEvent, DepositEvent, DepositFlowEvent, DepositMaxClickedEvent, DepositMethodClickedEvent, DepositOpenedEvent, DepositQuoteExpiredEvent, DepositQuoteFailedEvent, DepositQuoteRequestInput, DepositQuoteRequestedEvent, DepositQuoteResolvedEvent, DepositSettlementFailedEvent, DepositSettlementFailurePayload, DepositSettlementProgressedEvent, DepositSettlementResumedEvent, DepositSettlementSucceededEvent, DepositStepChangedEvent, DepositSubmissionBroadcastEvent, DepositSubmissionConfirmedEvent, DepositSubmissionDeclinedEvent, DepositSubmissionFailedEvent, DepositTransferAddressCopiedEvent, DepositTransferChainChangedEvent, DepositTransferTokenChangedEvent, DepositUiEvent } from "./types/deposit.js";
+import { KitEvent, KitSupportClickedEvent, KitTermsClickedEvent } from "./types/kit.js";
+import { WithdrawAmountChangedEvent, WithdrawBreakdownClickedEvent, WithdrawCancelPhase, WithdrawCancelledEvent, WithdrawClosedEvent, WithdrawEvent, WithdrawFlowEvent, WithdrawMaxClickedEvent, WithdrawOpenedEvent, WithdrawQuoteExpiredEvent, WithdrawQuoteFailedEvent, WithdrawQuoteRequestedEvent, WithdrawQuoteResolvedEvent, WithdrawReceiveChainChangedEvent, WithdrawReceiveTokenChangedEvent, WithdrawRecipientChangedEvent, WithdrawSettlementFailedEvent, WithdrawSettlementFailurePayload, WithdrawSettlementProgressedEvent, WithdrawSettlementSucceededEvent, WithdrawStepChangedEvent, WithdrawSubmissionBroadcastEvent, WithdrawSubmissionConfirmedEvent, WithdrawSubmissionDeclinedEvent, WithdrawSubmissionFailedEvent, WithdrawSubmitClickedEvent, WithdrawUiEvent } from "./types/withdraw.js";
+import { FlowEvent, FlowEventType, StridgeEvent, StridgeEventType, UiEvent, UiEventType } from "./types/index.js";
+import { useStridgeEvent } from "./hooks/useStridgeEvent.js";
+import { EventHandler } from "./bus/createBus.js";
+import { PublicStridgeEventBus, useStridgeEventBus } from "./hooks/useStridgeEventBus.js";
+import { useStridgeEvents } from "./hooks/useStridgeEvents.js";
+import { useStridgeFlowEvent } from "./hooks/useStridgeFlowEvent.js";
+import { useStridgeFlowEvents } from "./hooks/useStridgeFlowEvents.js";
+export { type DepositAmountChangedEvent, type DepositAmountSubmittedEvent, type DepositAssetClickedEvent, type DepositBackClickedEvent, type DepositCancelPhase, type DepositCancelledEvent, type DepositClosedEvent, type DepositConfirmClickedEvent, type DepositEvent, type DepositFlowEvent, type DepositMaxClickedEvent, type DepositMethodClickedEvent, type DepositOpenedEvent, type DepositQuoteExpiredEvent, type DepositQuoteFailedEvent, type DepositQuoteRequestInput, type DepositQuoteRequestedEvent, type DepositQuoteResolvedEvent, type DepositSettlementFailedEvent, type DepositSettlementFailurePayload, type DepositSettlementProgressedEvent, type DepositSettlementResumedEvent, type DepositSettlementSucceededEvent, type DepositStepChangedEvent, type DepositSubmissionBroadcastEvent, type DepositSubmissionConfirmedEvent, type DepositSubmissionDeclinedEvent, type DepositSubmissionFailedEvent, type DepositTransferAddressCopiedEvent, type DepositTransferChainChangedEvent, type DepositTransferTokenChangedEvent, type DepositUiEvent, type EventHandler, type FailureCode, type FailurePayloadBase, type FlowEvent, type FlowEventType, type FlowIdKey, type KitEvent, type KitSupportClickedEvent, type KitTermsClickedEvent, type PublicStridgeEventBus, type StridgeEvent, type StridgeEventBase, type StridgeEventFlow, type StridgeEventTier, type StridgeEventType, type UiEvent, type UiEventType, type WithdrawAmountChangedEvent, type WithdrawBreakdownClickedEvent, type WithdrawCancelPhase, type WithdrawCancelledEvent, type WithdrawClosedEvent, type WithdrawEvent, type WithdrawFlowEvent, type WithdrawMaxClickedEvent, type WithdrawOpenedEvent, type WithdrawQuoteExpiredEvent, type WithdrawQuoteFailedEvent, type WithdrawQuoteRequestedEvent, type WithdrawQuoteResolvedEvent, type WithdrawReceiveChainChangedEvent, type WithdrawReceiveTokenChangedEvent, type WithdrawRecipientChangedEvent, type WithdrawSettlementFailedEvent, type WithdrawSettlementFailurePayload, type WithdrawSettlementProgressedEvent, type WithdrawSettlementSucceededEvent, type WithdrawStepChangedEvent, type WithdrawSubmissionBroadcastEvent, type WithdrawSubmissionConfirmedEvent, type WithdrawSubmissionDeclinedEvent, type WithdrawSubmissionFailedEvent, type WithdrawSubmitClickedEvent, type WithdrawUiEvent, useCurrentFlowId, useStridgeEvent, useStridgeEventBus, useStridgeEvents, useStridgeFlowEvent, useStridgeFlowEvents };

package/dist/events/index.js

@@ -0,0 +1 @@
+import{useCurrentFlowId as e}from"./hooks/useCurrentFlowId.js";import{useStridgeEvent as t}from"./hooks/useStridgeEvent.js";import{useStridgeEventBus as n}from"./hooks/useStridgeEventBus.js";import{useStridgeEvents as r}from"./hooks/useStridgeEvents.js";import{useStridgeFlowEvent as i}from"./hooks/useStridgeFlowEvent.js";import{useStridgeFlowEvents as a}from"./hooks/useStridgeFlowEvents.js";import"./hooks/index.js";export{e as useCurrentFlowId,t as useStridgeEvent,n as useStridgeEventBus,r as useStridgeEvents,i as useStridgeFlowEvent,a as useStridgeFlowEvents};

package/dist/events/publish.js

@@ -0,0 +1 @@
+function e({bus:e,flowIds:t,metadata:n},r){let i=null;if(r.flow!==`kit`&&(i=t.current(r.flow),i===null)){process.env.NODE_ENV!==`production`&&console.warn(`[stridge/kit] tried to emit "${r.type}" but no active "${r.flow}" flow — the event was dropped. This usually means an emit fired before "opened" or after the terminal event.`);return}let a=r.flow===`kit`?{}:n.read(r.flow),o={type:r.type,flow:r.flow,tier:r.tier,timestamp:Date.now(),flowId:i,payload:r.payload,metadata:a};e.emit(o)}function t(t,n,i,a){r(n,a.flow,`openFlowSession`),t.flowIds.open(n),t.metadata.snapshot(n,i),e(t,{...a,flow:n})}function n(t,n,i){r(n,i.flow,`closeFlowSession`),e(t,{...i,flow:n}),t.flowIds.close(n),t.metadata.clear(n)}function r(e,t,n){process.env.NODE_ENV!==`production`&&e!==t&&console.error(`[stridge/kit] ${n}() called with flow="${e}" but partial.flow="${t}". Override applied (envelope will carry "${e}") but this is a sign of a copy-paste bug in the emit site.`)}export{n as closeFlowSession,t as openFlowSession,e as publishEvent};

package/dist/events/types/deposit.d.ts

@@ -0,0 +1,235 @@
+import { SettlementFailureKind, TxRef } from "../../shared/driver/types.js";
+import { BalanceItemPayload, QuotePayload, SettlementPendingPayload, SettlementSuccessPayload } from "../../flows/deposit/driver/payloads.js";
+import { DepositMethod, DepositStateName, ResolvedOpenInput } from "../../flows/deposit/orchestrator/types.js";
+import { TransferCryptoChain, TransferCryptoToken } from "../../flows/deposit/widgets/transfer-crypto/compound/types.js";
+import { FailurePayloadBase, StridgeEventBase } from "./envelope.js";
+
+//#region src/events/types/deposit.d.ts
+/**
+ * Orchestrator-level input the kit assembled to ask the driver for a deposit quote. Mirrors
+ * the shape of {@link import("#/flows/withdraw/driver").RequestWithdrawalQuoteInput} for the
+ * deposit side — wrapping the request fields in a single `input` field keeps the `payload`
+ * shape symmetric across flows so generic analytics handlers can write
+ * `track("quote_requested", e.payload.input)` for both flows.
+ */
+interface DepositQuoteRequestInput {
+  /** Source-side asset the user picked on the AssetPicker step. */
+  asset: BalanceItemPayload;
+  /** Send amount in display units. */
+  amount: number;
+}
+/**
+ * Phase the deposit flow was in when it was cancelled. Lets consumers distinguish "user
+ * abandoned at amount entry" from "user abandoned during processing wait" without parsing
+ * step names.
+ */
+type DepositCancelPhase = "quoting" | "confirming" | "submitting" | "processing" | "unknown";
+/**
+ * Settlement failure variant — extends the base with settlement-specific structure
+ * (typed `kind`, optional `txHash`) when the failure originates from the gateway's
+ * settlement entity rather than from a generic orchestrator path.
+ */
+interface DepositSettlementFailurePayload extends FailurePayloadBase {
+  /**
+   * Driver-classified failure kind for downstream branching. Bounded enum so consumers can
+   * `switch (e.payload.kind)` exhaustively. The kit also escalates FSM-level failures with
+   * `kind: "unknown"` when no settlement-specific classification applies.
+   */
+  kind: SettlementFailureKind;
+  /** On-chain transaction hash, when one was successfully broadcast before settlement failed. */
+  txHash?: TxRef;
+}
+/**
+ * Orchestrator asked the driver for a quote — either the first request for this asset/amount
+ * pair or a regeneration after expiry or signature decline. The payload carries the inputs
+ * the orchestrator used so consumers can correlate request → response.
+ */
+type DepositQuoteRequestedEvent = StridgeEventBase<"deposit.quote.requested", "deposit", "flow", {
+  input: DepositQuoteRequestInput;
+}>;
+/**
+ * Driver returned a successful quote and the orchestrator transitioned to `ready`. Payload is
+ * the full quote entity; reflect-then-render is safe (the orchestrator will not regenerate
+ * silently between this event and the next user action unless the quote expires).
+ */
+type DepositQuoteResolvedEvent = StridgeEventBase<"deposit.quote.resolved", "deposit", "flow", {
+  quote: QuotePayload;
+}>;
+/**
+ * Quote fetch failed. Payload is the standard {@link FailurePayloadBase} — same shape as every
+ * other `*.failed` event so generic error handlers work without per-event branching.
+ */
+type DepositQuoteFailedEvent = StridgeEventBase<"deposit.quote.failed", "deposit", "flow", FailurePayloadBase>;
+/**
+ * Active quote went stale (TTL elapsed) before the user could submit, and the orchestrator
+ * silently started regenerating it. Payload is empty — the next `deposit.quote.resolved`
+ * carries the replacement quote.
+ */
+type DepositQuoteExpiredEvent = StridgeEventBase<"deposit.quote.expired", "deposit", "flow", Record<string, never>>;
+/**
+ * Wallet broadcast the deposit transaction and the orchestrator transitioned into
+ * `processing`. The on-chain tx hash is now stable; settlement polling has started.
+ */
+type DepositSubmissionBroadcastEvent = StridgeEventBase<"deposit.submission.broadcast", "deposit", "flow", {
+  tx: TxRef;
+}>;
+/**
+ * User refused the wallet signature prompt. Distinct from {@link DepositSubmissionFailedEvent} —
+ * declining is a user choice, not an error. The orchestrator regenerates the quote and lands
+ * the user back on the confirm step.
+ */
+type DepositSubmissionDeclinedEvent = StridgeEventBase<"deposit.submission.declined", "deposit", "flow", Record<string, never>>;
+/**
+ * Submission attempted but couldn't complete — network failure, backend rejection, broken
+ * wallet provider, anything that isn't user-rejection. Carries the standard
+ * {@link FailurePayloadBase}.
+ */
+type DepositSubmissionFailedEvent = StridgeEventBase<"deposit.submission.failed", "deposit", "flow", FailurePayloadBase>;
+/**
+ * Background `fetchActiveSettlement` probe surfaced a pre-existing pending deposit on flow
+ * start — the user hadn't started this flow in this session but a prior unfinished deposit
+ * was detected and resumed. Payload is the settlement entity's pending snapshot.
+ *
+ * Withdraw has no symmetric event: the withdraw driver does not currently probe for
+ * pre-existing pending withdrawals (host-driven submission means the host already knows
+ * when a withdrawal was started). If withdraw later grows an equivalent probe, the
+ * symmetric `withdraw.settlement.resumed` will land at that time.
+ */
+type DepositSettlementResumedEvent = StridgeEventBase<"deposit.settlement.resumed", "deposit", "flow", {
+  settlement: SettlementPendingPayload;
+}>;
+/**
+ * Settlement entity emitted a progressive pending update — confirmations advancing, partial
+ * fill credited, etc. Fires once per update; payload always reflects the current snapshot.
+ */
+type DepositSettlementProgressedEvent = StridgeEventBase<"deposit.settlement.progressed", "deposit", "flow", {
+  settlement: SettlementPendingPayload;
+}>;
+/**
+ * Terminal success — settlement entity reached `ready{kind: "succeeded"}`. The flow is over;
+ * this event closes the session and the `flowId` is retired after it fires.
+ */
+type DepositSettlementSucceededEvent = StridgeEventBase<"deposit.settlement.succeeded", "deposit", "flow", {
+  settlement: SettlementSuccessPayload;
+}>;
+/**
+ * Terminal failure — settlement entity reached `ready{kind: "failed"}` (driver-emitted
+ * classification) or the orchestrator escalated an FSM-level failure to the global error arm.
+ * Payload extends the standard {@link FailurePayloadBase} with settlement-specific fields.
+ */
+type DepositSettlementFailedEvent = StridgeEventBase<"deposit.settlement.failed", "deposit", "flow", DepositSettlementFailurePayload>;
+/**
+ * Flow ended before reaching a terminal state — typically the user closed the dialog
+ * mid-flow, or an AbortSignal fired. `payload.phase` indicates where in the lifecycle the
+ * cancellation happened so consumers can build drop-off funnels without parsing step names.
+ */
+type DepositCancelledEvent = StridgeEventBase<"deposit.cancelled", "deposit", "flow", {
+  phase: DepositCancelPhase;
+}>;
+/** Union of every `deposit.*` `flow:*` event. */
+type DepositFlowEvent = DepositQuoteRequestedEvent | DepositQuoteResolvedEvent | DepositQuoteFailedEvent | DepositQuoteExpiredEvent | DepositSubmissionBroadcastEvent | DepositSubmissionDeclinedEvent | DepositSubmissionFailedEvent | DepositSettlementResumedEvent | DepositSettlementProgressedEvent | DepositSettlementSucceededEvent | DepositSettlementFailedEvent | DepositCancelledEvent;
+/**
+ * Dialog transitioned from `closed` to any open step. Mints the `flowId` (every subsequent
+ * event in this session carries the same `flowId`) and snapshots the `metadata` prop.
+ */
+type DepositOpenedEvent = StridgeEventBase<"deposit.opened", "deposit", "ui", {
+  input: ResolvedOpenInput;
+}>;
+/**
+ * Dialog returned to `closed`. `payload.atStep` is the step name the dialog was on at close
+ * time. Fires after any terminal event (`*.succeeded` / `*.failed`) or `deposit.cancelled`
+ * in the same session.
+ */
+type DepositClosedEvent = StridgeEventBase<"deposit.closed", "deposit", "ui", {
+  atStep: DepositStateName;
+}>;
+/**
+ * Dialog step transitioned. Fires on every logical step change including back-presses.
+ * `from === to` is not emitted; same-step `ctx` changes (e.g. `confirmDeposit` phase shifts)
+ * surface through their respective `flow:*` events instead.
+ */
+type DepositStepChangedEvent = StridgeEventBase<"deposit.step.changed", "deposit", "ui", {
+  from: DepositStateName;
+  to: DepositStateName;
+}>;
+/**
+ * User clicked a deposit method tile (`wallet` / `transfer`) on the entry step. Fires on
+ * commit — picking is the action that advances the FSM.
+ */
+type DepositMethodClickedEvent = StridgeEventBase<"deposit.method.clicked", "deposit", "ui", {
+  method: DepositMethod;
+}>;
+/**
+ * User clicked an asset row on the AssetPicker step. The asset is the driver-shaped balance row;
+ * use {@link BalanceItemPayload}'s `symbol` and `chainId` to identify it.
+ */
+type DepositAssetClickedEvent = StridgeEventBase<"deposit.asset.clicked", "deposit", "ui", {
+  asset: BalanceItemPayload;
+}>;
+/**
+ * User typed in the amount field on the AmountEntry step. Fires per keystroke (no debounce);
+ * `payload.raw` is the literal input string, `payload.numeric` is the parsed value (or `null`
+ * when empty / unparseable). Use this for live UI; use {@link DepositAmountSubmittedEvent} for
+ * commitment.
+ */
+type DepositAmountChangedEvent = StridgeEventBase<"deposit.amount.changed", "deposit", "ui", {
+  raw: string;
+  numeric: number | null;
+}>;
+/**
+ * User clicked the Max preset in the AmountEntry step (fills the amount with the full
+ * available balance). Mirrors {@link import("./withdraw").WithdrawMaxClickedEvent}.
+ */
+type DepositMaxClickedEvent = StridgeEventBase<"deposit.max.clicked", "deposit", "ui", Record<string, never>>;
+/**
+ * User submitted the AmountEntry step. `payload.amount` is the parsed numeric value (the FSM
+ * would not have advanced otherwise). The next event is typically `deposit.quote.requested`.
+ */
+type DepositAmountSubmittedEvent = StridgeEventBase<"deposit.amount.submitted", "deposit", "ui", {
+  amount: number;
+}>;
+/**
+ * User clicked the Confirm button on the ConfirmDeposit step. Fires unconditionally on click —
+ * even when the button is disabled / mid-submit — so analytics can observe intent regardless
+ * of whether the click triggers FSM advance. Mirrors
+ * {@link import("./withdraw").WithdrawSubmitClickedEvent}. Use
+ * {@link DepositSubmissionConfirmedEvent} for the FSM-level "submission accepted" signal.
+ */
+type DepositConfirmClickedEvent = StridgeEventBase<"deposit.confirm.clicked", "deposit", "ui", Record<string, never>>;
+/**
+ * Confirm-step FSM transition to the submitting phase — the wallet prompt is about to fire.
+ * Fires only when the FSM accepts the submission (the click was valid); for the raw click
+ * signal (regardless of validity), subscribe to {@link DepositConfirmClickedEvent}. The
+ * next event is typically `deposit.submission.broadcast`, `deposit.submission.declined`, or
+ * `deposit.submission.failed`.
+ */
+type DepositSubmissionConfirmedEvent = StridgeEventBase<"deposit.submission.confirmed", "deposit", "ui", Record<string, never>>;
+/**
+ * User clicked the Back chevron in the dialog header on a non-root step. `payload.fromStep` is
+ * the step they were leaving. Withdraw has no symmetric event — the withdraw dialog is
+ * single-form with no Back affordance (the dialog X closes the flow instead).
+ */
+type DepositBackClickedEvent = StridgeEventBase<"deposit.back.clicked", "deposit", "ui", {
+  fromStep: DepositStateName;
+}>;
+/**
+ * Inside the TransferCrypto compound, user picked a different source token. The selection
+ * affects which deposit address is shown but does not advance the FSM.
+ */
+type DepositTransferTokenChangedEvent = StridgeEventBase<"deposit.transfer.token.changed", "deposit", "ui", {
+  token: TransferCryptoToken;
+}>;
+/** Inside the TransferCrypto compound, user picked a different source chain. */
+type DepositTransferChainChangedEvent = StridgeEventBase<"deposit.transfer.chain.changed", "deposit", "ui", {
+  chain: TransferCryptoChain;
+}>;
+/** User clicked the copy-address button in the TransferCrypto compound. */
+type DepositTransferAddressCopiedEvent = StridgeEventBase<"deposit.transfer.address.copied", "deposit", "ui", {
+  address: string;
+}>;
+/** Union of every `deposit.*` `ui:*` event. */
+type DepositUiEvent = DepositOpenedEvent | DepositClosedEvent | DepositStepChangedEvent | DepositMethodClickedEvent | DepositAssetClickedEvent | DepositAmountChangedEvent | DepositMaxClickedEvent | DepositAmountSubmittedEvent | DepositConfirmClickedEvent | DepositSubmissionConfirmedEvent | DepositBackClickedEvent | DepositTransferTokenChangedEvent | DepositTransferChainChangedEvent | DepositTransferAddressCopiedEvent;
+/** Union of every `deposit.*` event regardless of tier. */
+type DepositEvent = DepositFlowEvent | DepositUiEvent;
+//#endregion
+export { DepositAmountChangedEvent, DepositAmountSubmittedEvent, DepositAssetClickedEvent, DepositBackClickedEvent, DepositCancelPhase, DepositCancelledEvent, DepositClosedEvent, DepositConfirmClickedEvent, DepositEvent, DepositFlowEvent, DepositMaxClickedEvent, DepositMethodClickedEvent, DepositOpenedEvent, DepositQuoteExpiredEvent, DepositQuoteFailedEvent, DepositQuoteRequestInput, DepositQuoteRequestedEvent, DepositQuoteResolvedEvent, DepositSettlementFailedEvent, DepositSettlementFailurePayload, DepositSettlementProgressedEvent, DepositSettlementResumedEvent, DepositSettlementSucceededEvent, DepositStepChangedEvent, DepositSubmissionBroadcastEvent, DepositSubmissionConfirmedEvent, DepositSubmissionDeclinedEvent, DepositSubmissionFailedEvent, DepositTransferAddressCopiedEvent, DepositTransferChainChangedEvent, DepositTransferTokenChangedEvent, DepositUiEvent };

package/dist/events/types/envelope.d.ts

@@ -0,0 +1,145 @@
+//#region src/events/types/envelope.d.ts
+/**
+ * Envelope, tier, flow, and failure types shared by every event variant in the unified bus.
+ *
+ * # Naming pattern (READ THIS BEFORE ADDING A NEW EVENT)
+ *
+ * Every event type is a string of the form `<flow>.<noun>.<verb-past>` (or
+ * `<flow>.<noun>.<sub-noun>.<verb-past>` for nested concepts):
+ *
+ * - `deposit.quote.resolved`
+ * - `withdraw.settlement.succeeded`
+ * - `deposit.transfer.address.copied`
+ * - `kit.support.opened`
+ *
+ * Rules:
+ *
+ * 1. **Lowercase, dot-segmented.** No camelCase, no colons, no slashes.
+ * 2. **Past-tense final verb.** Events describe things that already happened. `quote.resolved`,
+ *    not `quote.resolve`. Even in-flight signals use past tense (`quote.requested` — the
+ *    request *was made*).
+ * 3. **Same `noun.verb` across flows = same semantic concept.** A consumer who learns deposit
+ *    events should immediately recognise the withdraw equivalents. If a concept exists in both
+ *    flows, the trailing segments must match: `deposit.quote.resolved` ↔ `withdraw.quote.resolved`.
+ * 4. **Flow prefix is required.** Even for events that conceptually exist in both flows, each
+ *    flow gets its own typed variant. The prefix lets TypeScript narrow payloads precisely on
+ *    `e.type ===` checks without needing additional `e.flow ===` guards.
+ *
+ * # Tier rule
+ *
+ * - `tier: "flow"` — orchestrator/driver-emitted domain milestones (quote, submission,
+ *   settlement). Fire whether or not the user sees any UI, as long as the orchestrator is
+ *   running (which today means a dialog is mounted).
+ * - `tier: "ui"` — user-driven affordances and view-state changes from any kit-rendered
+ *   element. Includes dialog lifecycle (open / close / step.changed) and widget interactions
+ *   (keystrokes, selections, copy clicks). Fires only when the relevant kit-rendered component
+ *   is mounted.
+ *
+ * # Envelope shape
+ *
+ * Every event variant ships as a `StridgeEventBase<...>`. Field discipline:
+ *
+ * - `type` — unique string discriminator. Stable across versions; never reshape an existing
+ *   `type`. Adding a new event = adding a new variant to the appropriate union.
+ * - `flow` — duplicated from the `type` prefix for cheap field-based filtering by analytics
+ *   integrations that don't want to string-parse.
+ * - `tier` — duplicated from per-variant convention for filterable inspection.
+ * - `timestamp` — `Date.now()` at emit; wall-clock, not `performance.now()`, because
+ *   consumers want it for logging/funnels.
+ * - `flowId` — session correlation id. Minted at `<flow>.opened`, retired after the terminal
+ *   event (`*.settlement.succeeded` / `*.settlement.failed` / `*.cancelled`). Always
+ *   `string` for `flow:*` and `ui:*` events; `null` for `kit:*` events (which have no flow
+ *   context to belong to).
+ * - `payload` — event-specific data, always an object even when single-field, so future
+ *   fields can be added non-breakingly.
+ * - `metadata` — consumer-attached, snapshotted at `<flow>.opened` and frozen for the
+ *   session. Always present (empty object if the consumer didn't supply any). `Record<string,
+ *   unknown>` — the kit does not validate, normalise, or enforce a schema.
+ *
+ * # What's intentionally NOT in the envelope
+ *
+ * - No `id` per-event uuid — `flowId + type + timestamp` is sufficient correlation.
+ * - No `preventDefault` / `stopPropagation` — events are read-only notifications.
+ * - No `version` field — versioning happens through the union, not at runtime.
+ * - No `source: "user" | "system"` distinction beyond `tier` — adding finer grain invites
+ *   bikeshed without paying for itself.
+ */
+/** Flow identifier — one per orchestrator family, plus `"kit"` for flow-less provider events. */
+type StridgeEventFlow = "deposit" | "withdraw" | "kit";
+/** Delivery tier — see envelope JSDoc for the rule. */
+type StridgeEventTier = "flow" | "ui";
+/**
+ * Generic envelope every event variant extends. Concrete variants narrow the four type
+ * parameters so `e.type === "..."` discrimination narrows `flow`, `tier`, and `payload`
+ * in lockstep.
+ */
+interface StridgeEventBase<TType extends string, TFlow extends StridgeEventFlow, TTier extends StridgeEventTier, TPayload> {
+  /** Stable string discriminator. See the naming pattern in this file's top-of-file JSDoc. */
+  type: TType;
+  /** Originating flow. Always derivable from the `type` prefix; duplicated for cheap field-based filtering. */
+  flow: TFlow;
+  /** Delivery tier. */
+  tier: TTier;
+  /** Wall-clock millisecond timestamp at emit. */
+  timestamp: number;
+  /**
+   * Session correlation id. `string` for flow-scoped events, `null` for `kit:*` events
+   * (which have no flow context to belong to).
+   */
+  flowId: TFlow extends "kit" ? null : string;
+  /** Event-specific payload. Always an object even when single-field. */
+  payload: TPayload;
+  /**
+   * Consumer-attached metadata, snapshotted at `<flow>.opened`, frozen for the session.
+   * Empty object when the consumer didn't supply any. Consumer-typed at the consumption
+   * site — the kit does not validate or normalise.
+   */
+  metadata: Record<string, unknown>;
+}
+/**
+ * Stable taxonomy of failure codes carried by every `*.failed` event. Constrained enum (not
+ * free string) because consumers writing `switch(code)` need exhaustiveness and analytics
+ * platforms need bounded cardinality.
+ *
+ * Every internal failure path must map to one of these. Add new codes here when a new
+ * failure category genuinely appears — don't widen the union with overlapping codes.
+ */
+type FailureCode = /** Transport-level fetch failure, DNS error, browser offline. */"network" /** Operation exceeded its deadline before producing a result. */ | "timeout" /** Backend returned 429 / equivalent rate-limit signal. */ | "rate_limited" /** Gateway key invalid, scope mismatch, or session expired. */ | "unauthorized" /** Requested amount exceeds available balance. */ | "insufficient_funds" /** Backend rejected the payload as malformed (validation failure). */ | "invalid_input" /** Quote went stale between request and submit. */ | "quote_expired" /** On-chain transaction reverted. */ | "tx_reverted" /** Transaction replaced or dropped from the mempool before inclusion. */ | "tx_dropped" /** Backend couldn't correlate a settlement to the submitted transaction. */ | "settlement_lost" /** Catch-all for anything else; consumers should treat as opaque. */ | "internal";
+/**
+ * Shape carried by every `*.failed` event in the bus. Common base lets generic error handlers
+ * write `analytics.track("error", e.payload.code, e.payload.reason)` once and have it work
+ * across every flow and every failure point.
+ *
+ * Per-event extensions (e.g. `SettlementFailurePayload`) extend this with richer fields when
+ * the failure has additional structure worth surfacing.
+ *
+ * **`.declined` (user refused a wallet prompt) and `.cancelled` (flow interrupted by close /
+ * AbortSignal) are NOT `.failed`** — they have their own event names with their own (often
+ * empty) payloads. Conflating them would let analytics count user choices as errors.
+ */
+interface FailurePayloadBase {
+  /**
+   * Stable taxonomy code. Drives consumer logic: retry decisions, custom messaging,
+   * error-grouping in analytics dashboards.
+   */
+  code: FailureCode;
+  /**
+   * Human-readable reason, already localised by the kit. Safe to render directly to users.
+   * Consumers who want raw keys for their own messaging branch on {@link code} instead.
+   */
+  reason: string;
+  /**
+   * Whether retrying the same operation could plausibly succeed. `true` for transient
+   * failures (`network`, `timeout`, `rate_limited`); `false` for permanent ones
+   * (`unauthorized`, `invalid_input`, `tx_reverted`).
+   */
+  retryable: boolean;
+  /**
+   * Raw cause for debugging only — typically the underlying `Error`, fetch `Response`, or
+   * wallet-provider error object. Never displayed; safe to log. Consumers must not depend
+   * on its shape.
+   */
+  cause?: unknown;
+}
+//#endregion
+export { FailureCode, FailurePayloadBase, StridgeEventBase, StridgeEventFlow, StridgeEventTier };

package/dist/events/types/index.d.ts

@@ -0,0 +1,31 @@
+import { FailureCode, FailurePayloadBase, StridgeEventBase, StridgeEventFlow, StridgeEventTier } from "./envelope.js";
+import { DepositAmountChangedEvent, DepositAmountSubmittedEvent, DepositAssetClickedEvent, DepositBackClickedEvent, DepositCancelPhase, DepositCancelledEvent, DepositClosedEvent, DepositConfirmClickedEvent, DepositEvent, DepositFlowEvent, DepositMaxClickedEvent, DepositMethodClickedEvent, DepositOpenedEvent, DepositQuoteExpiredEvent, DepositQuoteFailedEvent, DepositQuoteRequestInput, DepositQuoteRequestedEvent, DepositQuoteResolvedEvent, DepositSettlementFailedEvent, DepositSettlementFailurePayload, DepositSettlementProgressedEvent, DepositSettlementResumedEvent, DepositSettlementSucceededEvent, DepositStepChangedEvent, DepositSubmissionBroadcastEvent, DepositSubmissionConfirmedEvent, DepositSubmissionDeclinedEvent, DepositSubmissionFailedEvent, DepositTransferAddressCopiedEvent, DepositTransferChainChangedEvent, DepositTransferTokenChangedEvent, DepositUiEvent } from "./deposit.js";
+import { KitEvent, KitSupportClickedEvent, KitTermsClickedEvent } from "./kit.js";
+import { WithdrawAmountChangedEvent, WithdrawBreakdownClickedEvent, WithdrawCancelPhase, WithdrawCancelledEvent, WithdrawClosedEvent, WithdrawEvent, WithdrawFlowEvent, WithdrawMaxClickedEvent, WithdrawOpenedEvent, WithdrawQuoteExpiredEvent, WithdrawQuoteFailedEvent, WithdrawQuoteRequestedEvent, WithdrawQuoteResolvedEvent, WithdrawReceiveChainChangedEvent, WithdrawReceiveTokenChangedEvent, WithdrawRecipientChangedEvent, WithdrawSettlementFailedEvent, WithdrawSettlementFailurePayload, WithdrawSettlementProgressedEvent, WithdrawSettlementSucceededEvent, WithdrawStepChangedEvent, WithdrawSubmissionBroadcastEvent, WithdrawSubmissionConfirmedEvent, WithdrawSubmissionDeclinedEvent, WithdrawSubmissionFailedEvent, WithdrawSubmitClickedEvent, WithdrawUiEvent } from "./withdraw.js";
+
+//#region src/events/types/index.d.ts
+/**
+ * Every `flow:*` event across all flows. Headless-safe — this is what
+ * `useStridgeFlowEvents` narrows its handler to. Does not include any `ui:*` or `kit:*`
+ * events; consumers who only render the dialog (no widgets, no provider affordances) can
+ * subscribe to this union and never see a UI-noise event in their autocomplete.
+ */
+type FlowEvent = DepositFlowEvent | WithdrawFlowEvent;
+/**
+ * Every `ui:*` event across all flows, plus every `kit:*` provider-scoped event (kit
+ * affordances are user-driven, so they share the `ui` tier today even though they don't
+ * belong to a deposit/withdraw flow). Does NOT include `flow:*` events — for the firehose
+ * union, use {@link StridgeEvent}.
+ */
+type UiEvent = DepositUiEvent | WithdrawUiEvent | KitEvent;
+/**
+ * Firehose union — every event the kit ever emits. Equivalent to `FlowEvent | UiEvent`.
+ * What `useStridgeEvents` hands to its handler.
+ */
+type StridgeEvent = FlowEvent | UiEvent;
+/** Convenience: every distinct `type` literal across the full union. */
+type StridgeEventType = StridgeEvent["type"];
+type FlowEventType = FlowEvent["type"];
+type UiEventType = UiEvent["type"];
+//#endregion
+export { FlowEvent, FlowEventType, StridgeEvent, StridgeEventType, UiEvent, UiEventType };

package/dist/events/types/kit.d.ts

@@ -0,0 +1,23 @@
+import { SupportOpenContext } from "../../shared/support/types.js";
+import { TermsSelectContext } from "../../shared/terms/types.js";
+import { StridgeEventBase } from "./envelope.js";
+//#region src/events/types/kit.d.ts
+/**
+ * User clicked the support entry point (the "Get help" link / button). Fires regardless of
+ * whether the consumer provided a custom `support.onOpen` handler — the bus event is an
+ * observation channel for analytics, the prop is a behaviour-override contract. Both coexist.
+ */
+type KitSupportClickedEvent = StridgeEventBase<"kit.support.clicked", "kit", "ui", {
+  context: SupportOpenContext;
+}>;
+/**
+ * User clicked a terms link. Fires regardless of whether the consumer provided a custom
+ * `terms.onSelect` handler.
+ */
+type KitTermsClickedEvent = StridgeEventBase<"kit.terms.clicked", "kit", "ui", {
+  context: TermsSelectContext;
+}>;
+/** Union of every `kit.*` event. */
+type KitEvent = KitSupportClickedEvent | KitTermsClickedEvent;
+//#endregion
+export { KitEvent, KitSupportClickedEvent, KitTermsClickedEvent };