@symmio/trading-react 3.0.0 → 3.1.0

package/dist/gasless/use-gasless-relay-confirmation.js

@@ -0,0 +1,148 @@
+"use client";
+import { normalizeSymmError as e } from "../errors/normalize-symm-error.js";
+import { IDLE_RELAY_PROGRESS as t } from "./gasless-relay-types.js";
+import { GaslessRequestStatus as n, confirmGaslessRequest as r, getGaslessRequestQueryKey as i, isNewerGaslessRequest as a } from "@symmio/trading-core";
+import { useCallback as o, useEffect as s, useRef as c, useState as l } from "react";
+import { useQueryClient as u } from "@tanstack/react-query";
+//#region src/gasless/use-gasless-relay-confirmation.ts
+var d = new Set(["GASLESS_TERMINAL_TIMEOUT", "GASLESS_BROADCAST_TIMEOUT"]);
+function f(e) {
+	return e.walletIds ? e.walletIds : e.walletId === void 0 ? [] : [e.walletId];
+}
+function p(p, g) {
+	let _ = u(), [v, y] = l(t), b = c(void 0), x = c(!0), S = c(p.abortOnUnmount ?? !0);
+	S.current = p.abortOnUnmount ?? !0, s(() => (x.current = !0, () => {
+		x.current = !1, S.current && b.current?.abort();
+	}), []);
+	let C = o((e) => {
+		x.current && y(e);
+	}, []);
+	return {
+		progress: v,
+		reset: o(() => {
+			b.current?.abort(), b.current = void 0, C(t);
+		}, [C]),
+		submit: o(async (e) => {
+			C({
+				phase: "submitting",
+				degraded: !1
+			});
+			try {
+				return await e();
+			} catch (e) {
+				throw C({
+					phase: "error",
+					degraded: !1
+				}), e;
+			}
+		}, [C]),
+		confirm: o(async (t, o) => {
+			let { chainId: s, service: c, invalidate: l } = o, { confirmation: u = "receipt" } = p;
+			try {
+				p.onAccepted?.({
+					requestId: t.requestId,
+					service: c ?? "operations",
+					chainId: s,
+					protocolInstance: t.protocolInstance,
+					idempotencyKey: t.idempotencyKey,
+					operationType: o.operationType ?? null,
+					owner: t.owner,
+					walletIds: f(t)
+				});
+			} catch {}
+			let v = !1, y, x = (e) => {
+				C({
+					...e,
+					idempotencyKey: t.idempotencyKey,
+					degraded: v,
+					issue: y
+				});
+			};
+			if (x({
+				phase: "queued",
+				requestId: t.requestId,
+				status: n.QUEUED
+			}), u === "none") return;
+			b.current?.abort();
+			let S = new AbortController();
+			b.current = S;
+			let w = !1, T, E = null, D = g.getChainConfigKey(s), O = () => b.current === S, k = (e) => {
+				e.status === n.SUCCEEDED && (w = !0), T = e.status, E = e.txHash, v = !1, y = void 0, _.setQueryData(i({
+					chainId: s,
+					requestId: t.requestId,
+					service: c,
+					configKey: D
+				}), (t) => a(t, e) ? e : t), O() && x({
+					phase: e.status === n.SUBMITTED ? "submitted" : "queued",
+					requestId: e.requestId,
+					status: e.status,
+					txHash: e.txHash ?? void 0
+				}), p.onProgress?.(e);
+			};
+			try {
+				let i = await r(g, {
+					chainId: s,
+					requestId: t.requestId,
+					service: c ?? "operations",
+					until: u,
+					receiptConfirmations: p.receiptConfirmations,
+					timeoutMs: p.timeoutMs,
+					receiptTimeoutMs: p.receiptTimeoutMs,
+					signal: S.signal,
+					onTransportIssue: (r) => {
+						v = !0, y = e(r), O() && x({
+							phase: T === n.SUBMITTED ? "submitted" : "queued",
+							requestId: t.requestId,
+							status: T,
+							txHash: E ?? void 0
+						});
+					},
+					onUpdate: (e) => {
+						k(e), e.status === n.SUCCEEDED && u === "receipt" && O() && x({
+							phase: "awaiting-receipt",
+							requestId: e.requestId,
+							status: e.status,
+							txHash: e.txHash ?? void 0
+						});
+					}
+				});
+				return O() && x({
+					phase: "confirmed",
+					requestId: i.request.requestId,
+					status: i.request.status,
+					txHash: i.txHash
+				}), i;
+			} catch (e) {
+				if (O()) {
+					let n = d.has(m(e)) ? "unconfirmed" : "error";
+					x({
+						phase: n,
+						requestId: t.requestId,
+						status: h(e) ?? (n === "unconfirmed" ? T : void 0),
+						txHash: E ?? void 0
+					});
+				}
+				throw e;
+			} finally {
+				w && l(_), b.current === S && (b.current = void 0);
+			}
+		}, [
+			g,
+			p,
+			C,
+			_
+		])
+	};
+}
+function m(e) {
+	let t = e?.code;
+	return typeof t == "string" ? t : "";
+}
+function h(e) {
+	let t = e?.responseData?.status;
+	return typeof t == "string" && Object.values(n).includes(t) ? t : void 0;
+}
+//#endregion
+export { p as useGaslessRelayConfirmation };
+
+//# sourceMappingURL=use-gasless-relay-confirmation.js.map

package/dist/gasless/use-gasless-relay-confirmation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gasless-relay-confirmation.js","names":[],"sources":["../../src/gasless/use-gasless-relay-confirmation.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  confirmGaslessRequest,\n  GaslessRequestStatus,\n  getGaslessRequestQueryKey,\n  isNewerGaslessRequest,\n  type Config,\n  type GaslessAcceptedRequest,\n  type GaslessConfirmedRequest,\n  type GaslessRequest,\n  type GaslessService,\n} from \"@symmio/trading-core\";\nimport { useQueryClient, type QueryClient } from \"@tanstack/react-query\";\nimport { useCallback, useEffect, useRef, useState } from \"react\";\nimport type { Address } from \"viem\";\nimport { normalizeSymmError } from \"../errors/normalize-symm-error\";\nimport { IDLE_RELAY_PROGRESS, type GaslessRelayParameters, type GaslessRelayProgress } from \"./gasless-relay-types\";\n\n/**\n * The acceptance fields a confirmation needs. Every gasless submit receipt\n * satisfies it: an operations receipt carries `walletIds`, a deposit settlement\n * carries the single `walletId` it settled.\n *\n * @internal\n */\nexport interface GaslessRelayAcceptance {\n  requestId: string;\n  idempotencyKey: string;\n  protocolInstance: string | null;\n  owner: Address;\n  walletIds?: readonly bigint[];\n  walletId?: bigint;\n}\n\n/** What the relay hook tells the confirmation about the request it just submitted. @internal */\nexport interface GaslessRelayConfirmOptions {\n  /** The chain the relay was accepted on. */\n  chainId: number;\n  /** Which sub-service stores the request. Defaults to `\"operations\"`. */\n  service?: GaslessService;\n  /** The workflow label the submit carried, for the persisted row. */\n  operationType?: string;\n  /** Invalidate the reads a `succeeded` relay changed. */\n  invalidate: (queryClient: QueryClient) => void;\n}\n\n/** What {@link useGaslessRelayConfirmation} hands back to a relay hook. */\nexport interface GaslessRelayConfirmationController {\n  /** Current progress, to merge onto the mutation result as `relay`. */\n  progress: GaslessRelayProgress;\n  /** Reset progress and abort any in-flight wait. Call from the hook's `reset`. */\n  reset: () => void;\n  /**\n   * Run the submit half of a relay through the progress state.\n   *\n   * Publishes `submitting` for the window between the user's click and the\n   * service's `202` — signing and the POST — which is the one stretch\n   * {@link confirm} cannot see, and publishes `error` if that window fails.\n   * Nothing is accepted yet, so neither phase carries a request id.\n   */\n  submit: <result>(send: () => Promise<result>) => Promise<result>;\n  /**\n   * Follow an accepted request to the configured depth.\n   *\n   * Returns the confirmation, or `undefined` for `confirmation: \"none\"`.\n   * `invalidate` runs whenever a `succeeded` terminal was observed — including\n   * when the wait was later aborted — because the point of waiting is the\n   * invalidation, and the query client outlives the component.\n   */\n  confirm: (\n    accepted: GaslessRelayAcceptance,\n    options: GaslessRelayConfirmOptions,\n  ) => Promise<GaslessConfirmedRequest | undefined>;\n}\n\n/** The wait budget ran out: the outcome is unknown, not failed. */\nconst TIMEOUT_CODES: ReadonlySet<string> = new Set([\"GASLESS_TERMINAL_TIMEOUT\", \"GASLESS_BROADCAST_TIMEOUT\"]);\n\n/** The ids a relay selected, whichever shape its acceptance reports them in. */\nfunction acceptedWalletIds(accepted: GaslessRelayAcceptance): readonly bigint[] {\n  if (accepted.walletIds) return accepted.walletIds;\n  return accepted.walletId === undefined ? [] : [accepted.walletId];\n}\n\n/**\n * The confirmation half of every explicit relay hook.\n *\n * Owns the four things a relay mutation needs and a plain `useMutation` cannot\n * give it: an `AbortController` tied to the component's life, progress state\n * that survives a 120-second wait, the `onAccepted` hand-off that lets a\n * consumer persist the request id before anything can go wrong, and the\n * guarantee that a `succeeded` relay invalidates its reads even if nobody is\n * left watching.\n *\n * @param parameters - The hook's confirmation options.\n * @param config - The SDK config, for the confirm call and the cache seed.\n *\n * @internal\n */\nexport function useGaslessRelayConfirmation(\n  parameters: GaslessRelayParameters,\n  config: Config,\n): GaslessRelayConfirmationController {\n  const queryClient = useQueryClient();\n  const [progress, setProgress] = useState<GaslessRelayProgress>(IDLE_RELAY_PROGRESS);\n\n  const abortRef = useRef<AbortController>(undefined);\n  const mountedRef = useRef(true);\n\n  /**\n   * Held in a ref, and the effect has no dependencies, so the cleanup runs on\n   * unmount only. Depending on the value would re-run the cleanup whenever a\n   * caller flipped the flag — aborting a live confirmation, and doing so on\n   * exactly the `true -> false` transition that asks for the opposite.\n   */\n  const abortOnUnmountRef = useRef(parameters.abortOnUnmount ?? true);\n  abortOnUnmountRef.current = parameters.abortOnUnmount ?? true;\n\n  useEffect(() => {\n    mountedRef.current = true;\n    return () => {\n      mountedRef.current = false;\n      if (abortOnUnmountRef.current) abortRef.current?.abort();\n    };\n  }, []);\n\n  /** Progress is cosmetic — never let a late setState warn after unmount. */\n  const publish = useCallback((next: GaslessRelayProgress) => {\n    if (mountedRef.current) setProgress(next);\n  }, []);\n\n  const reset = useCallback(() => {\n    abortRef.current?.abort();\n    abortRef.current = undefined;\n    publish(IDLE_RELAY_PROGRESS);\n  }, [publish]);\n\n  const submit = useCallback(\n    async <result>(send: () => Promise<result>): Promise<result> => {\n      publish({ phase: \"submitting\", degraded: false });\n      try {\n        return await send();\n      } catch (err) {\n        /**\n         * The service never accepted anything, so there is no id to report and\n         * no workflow to keep watching: unlike a failed confirmation, this one\n         * is safe to retry from the wallet.\n         */\n        publish({ phase: \"error\", degraded: false });\n        throw err;\n      }\n    },\n    [publish],\n  );\n\n  const confirm = useCallback(\n    async (accepted: GaslessRelayAcceptance, options: GaslessRelayConfirmOptions) => {\n      const { chainId, service, invalidate } = options;\n      const { confirmation = \"receipt\" } = parameters;\n\n      /**\n       * Before anything can fail: the request exists server-side from this\n       * point on, and its id is the only handle on it.\n       */\n      try {\n        parameters.onAccepted?.({\n          requestId: accepted.requestId,\n          service: service ?? \"operations\",\n          chainId,\n          protocolInstance: accepted.protocolInstance,\n          idempotencyKey: accepted.idempotencyKey,\n          operationType: options.operationType ?? null,\n          owner: accepted.owner,\n          walletIds: acceptedWalletIds(accepted),\n        } satisfies GaslessAcceptedRequest);\n      } catch {\n        /** An observer must never fail a relay the service has already accepted. */\n      }\n\n      /** Reported on every publish, so a transient blind spot never reads as a failure. */\n      let degraded = false;\n      let issue: GaslessRelayProgress[\"issue\"];\n\n      const publishPhase = (next: Omit<GaslessRelayProgress, \"degraded\" | \"issue\" | \"idempotencyKey\">) => {\n        publish({ ...next, idempotencyKey: accepted.idempotencyKey, degraded, issue });\n      };\n\n      publishPhase({\n        phase: \"queued\",\n        requestId: accepted.requestId,\n        status: GaslessRequestStatus.QUEUED,\n      });\n      if (confirmation === \"none\") return undefined;\n\n      /** A second submit supersedes the first: stop watching the old one. */\n      abortRef.current?.abort();\n      const controller = new AbortController();\n      abortRef.current = controller;\n\n      let sawSuccess = false;\n      let lastStatus: GaslessRequestStatus | undefined;\n      let lastTxHash: GaslessRequest[\"txHash\"] = null;\n      const configKey = config.getChainConfigKey(chainId);\n\n      /** A superseded or aborted wait must not paint over the live one. */\n      const isCurrent = () => abortRef.current === controller;\n\n      const onUpdate = (request: GaslessRequest) => {\n        if (request.status === GaslessRequestStatus.SUCCEEDED) sawSuccess = true;\n        lastStatus = request.status;\n        lastTxHash = request.txHash;\n        /** A read landed: whatever was unreadable a moment ago is readable again. */\n        degraded = false;\n        issue = undefined;\n        /**\n         * Seed the record so a separately mounted `useGaslessRequest` on the\n         * same id sees terminal immediately instead of running its own poll —\n         * but only when it is genuinely newer, or a slow `queued` response\n         * would repaint a finished workflow as pending.\n         */\n        queryClient.setQueryData<GaslessRequest>(\n          getGaslessRequestQueryKey({ chainId, requestId: accepted.requestId, service, configKey }),\n          (previous) => (isNewerGaslessRequest(previous, request) ? request : previous),\n        );\n        if (isCurrent()) {\n          publishPhase({\n            phase: request.status === GaslessRequestStatus.SUBMITTED ? \"submitted\" : \"queued\",\n            requestId: request.requestId,\n            status: request.status,\n            txHash: request.txHash ?? undefined,\n          });\n        }\n        parameters.onProgress?.(request);\n      };\n\n      try {\n        const confirmed = await confirmGaslessRequest(config, {\n          chainId,\n          requestId: accepted.requestId,\n          service: service ?? \"operations\",\n          until: confirmation,\n          receiptConfirmations: parameters.receiptConfirmations,\n          timeoutMs: parameters.timeoutMs,\n          receiptTimeoutMs: parameters.receiptTimeoutMs,\n          signal: controller.signal,\n          onTransportIssue: (error) => {\n            degraded = true;\n            issue = normalizeSymmError(error);\n            if (isCurrent()) {\n              publishPhase({\n                phase: lastStatus === GaslessRequestStatus.SUBMITTED ? \"submitted\" : \"queued\",\n                requestId: accepted.requestId,\n                status: lastStatus,\n                txHash: lastTxHash ?? undefined,\n              });\n            }\n          },\n          onUpdate: (request) => {\n            onUpdate(request);\n            if (request.status === GaslessRequestStatus.SUCCEEDED && confirmation === \"receipt\" && isCurrent()) {\n              publishPhase({\n                phase: \"awaiting-receipt\",\n                requestId: request.requestId,\n                status: request.status,\n                txHash: request.txHash ?? undefined,\n              });\n            }\n          },\n        });\n        if (isCurrent()) {\n          publishPhase({\n            phase: \"confirmed\",\n            requestId: confirmed.request.requestId,\n            status: confirmed.request.status,\n            txHash: confirmed.txHash,\n          });\n        }\n        return confirmed;\n      } catch (err) {\n        if (isCurrent()) {\n          /**\n           * A budget that ran out is not a verdict: the relay is still running\n           * and its id is still good. The mutation rejects either way — it has\n           * no result to report — but the phase must not tell the user their\n           * action failed, which is what makes them submit it a second time.\n           */\n          const phase = TIMEOUT_CODES.has(readErrorCode(err)) ? \"unconfirmed\" : \"error\";\n          publishPhase({\n            phase,\n            requestId: accepted.requestId,\n            status: progressStatus(err) ?? (phase === \"unconfirmed\" ? lastStatus : undefined),\n            txHash: lastTxHash ?? undefined,\n          });\n        }\n        throw err;\n      } finally {\n        /**\n         * Gated on the observed terminal, not on how the wait ended: an abort\n         * after `succeeded` still leaves the cache stale for everyone else.\n         */\n        if (sawSuccess) invalidate(queryClient);\n        if (abortRef.current === controller) abortRef.current = undefined;\n      }\n    },\n    [config, parameters, publish, queryClient],\n  );\n\n  return { progress, reset, submit, confirm };\n}\n\n/** The SDK error code an error carries, read structurally across the error layers. */\nfunction readErrorCode(err: unknown): string {\n  const code = (err as { code?: unknown } | undefined)?.code;\n  return typeof code === \"string\" ? code : \"\";\n}\n\n/** Best-effort status for the error phase; absent when the failure was transport-level. */\nfunction progressStatus(err: unknown): GaslessRequestStatus | undefined {\n  const data = (err as { responseData?: { status?: unknown } } | undefined)?.responseData;\n  const status = data?.status;\n  return typeof status === \"string\" && (Object.values(GaslessRequestStatus) as string[]).includes(status)\n    ? (status as GaslessRequestStatus)\n    : undefined;\n}\n"],"mappings":"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"}

package/dist/gasless/use-gasless-request-stream.d.ts

@@ -0,0 +1,34 @@
+import { Config, GaslessService, GaslessStatusTransport, GaslessStreamStatus, GaslessStreamStatusDetail } from '@symmio/trading-core';
+/** What {@link useGaslessRequestStream} reports about the live transport. */
+export interface GaslessStreamState {
+    /** Stream health; anything but `"live"` means the caller should keep polling. */
+    status: GaslessStreamStatus;
+    /** Why, when the status alone does not say. */
+    detail: GaslessStreamStatusDetail | null;
+    /** Convenience for gating a poll: `status === "live"`. */
+    live: boolean;
+}
+/**
+ * Subscribe one workflow to the gateway's status stream and push its records
+ * into the query cache.
+ *
+ * The hook owns no data of its own: every delivery is written to the same cache
+ * entries the HTTP reads use, so components keep reading through
+ * `useGaslessRequest` / `useGaslessRequestTransactions` and never learn which
+ * transport produced a record. It returns only the stream's health, which the
+ * caller uses to pause or resume its poll — the pattern `usePrices` uses for the
+ * price feed.
+ *
+ * A deployment without a stream, or a disabled one, simply stays `"idle"`.
+ *
+ * @internal
+ */
+export declare function useGaslessRequestStream(parameters: {
+    config: Config;
+    chainId: number;
+    requestId: string;
+    service?: GaslessService;
+    enabled: boolean;
+    transport?: GaslessStatusTransport;
+}): GaslessStreamState;
+//# sourceMappingURL=use-gasless-request-stream.d.ts.map

package/dist/gasless/use-gasless-request-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gasless-request-stream.d.ts","sourceRoot":"","sources":["../../src/gasless/use-gasless-request-stream.ts"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,MAAM,EAEX,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC/B,MAAM,sBAAsB,CAAC;AAI9B,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,MAAM,EAAE,mBAAmB,CAAC;IAC5B,+CAA+C;IAC/C,MAAM,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACzC,0DAA0D;IAC1D,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC,GAAG,kBAAkB,CA8DrB"}

package/dist/gasless/use-gasless-request-stream.js

@@ -0,0 +1,86 @@
+"use client";
+import { getGaslessRequestQueryKey as e, getGaslessRequestTransactionsQueryKey as t, isGaslessRequestTerminal as n, supportsGaslessStatusStream as r, watchGaslessRequest as i } from "@symmio/trading-core";
+import { useEffect as a, useState as o } from "react";
+import { useQueryClient as s } from "@tanstack/react-query";
+//#region src/gasless/use-gasless-request-stream.ts
+function c(n) {
+	let { config: c, chainId: u, requestId: d, service: f = "operations", enabled: p, transport: m = "auto" } = n, h = s(), [g, _] = o({
+		status: "idle",
+		detail: null,
+		live: !1
+	}), v = p && d.length > 0 && m !== "poll" && r(c, {
+		chainId: u,
+		service: f
+	});
+	return a(() => {
+		if (!v) {
+			_({
+				status: "idle",
+				detail: null,
+				live: !1
+			});
+			return;
+		}
+		let n = c.getChainConfigKey(u), r = e({
+			chainId: u,
+			requestId: d,
+			service: f,
+			configKey: n
+		}), a = t({
+			chainId: u,
+			requestId: d,
+			service: f,
+			configKey: n
+		}), o;
+		try {
+			o = i(c, {
+				chainId: u,
+				requestId: d,
+				service: f,
+				onUpdate: ({ request: e, transactions: t }) => {
+					e && (h.cancelQueries({
+						queryKey: r,
+						exact: !0
+					}), h.setQueryData(r, (t) => t && l(t, e) ? t : e)), t.length > 0 && (h.cancelQueries({
+						queryKey: a,
+						exact: !0
+					}), h.setQueryData(a, t));
+				},
+				onStatusChange: (e, t) => _({
+					status: e,
+					detail: t,
+					live: e === "live"
+				}),
+				onError: () => {}
+			});
+		} catch {
+			_({
+				status: "idle",
+				detail: null,
+				live: !1
+			});
+			return;
+		}
+		return () => {
+			o?.(), _({
+				status: "idle",
+				detail: null,
+				live: !1
+			});
+		};
+	}, [
+		v,
+		c,
+		u,
+		d,
+		f,
+		h
+	]), g;
+}
+function l(e, t) {
+	return n(e.status) && !n(t.status) ? !0 : e.updatedAt && t.updatedAt ? e.updatedAt > t.updatedAt : !1;
+}
+//#endregion
+export { c as useGaslessRequestStream };
+
+//# sourceMappingURL=use-gasless-request-stream.js.map

package/dist/gasless/use-gasless-request-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gasless-request-stream.js","names":[],"sources":["../../src/gasless/use-gasless-request-stream.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  getGaslessRequestQueryKey,\n  getGaslessRequestTransactionsQueryKey,\n  isGaslessRequestTerminal,\n  supportsGaslessStatusStream,\n  watchGaslessRequest,\n  type Config,\n  type GaslessRequest,\n  type GaslessService,\n  type GaslessStatusTransport,\n  type GaslessStreamStatus,\n  type GaslessStreamStatusDetail,\n} from \"@symmio/trading-core\";\nimport { useQueryClient } from \"@tanstack/react-query\";\nimport { useEffect, useState } from \"react\";\n\n/** What {@link useGaslessRequestStream} reports about the live transport. */\nexport interface GaslessStreamState {\n  /** Stream health; anything but `\"live\"` means the caller should keep polling. */\n  status: GaslessStreamStatus;\n  /** Why, when the status alone does not say. */\n  detail: GaslessStreamStatusDetail | null;\n  /** Convenience for gating a poll: `status === \"live\"`. */\n  live: boolean;\n}\n\n/**\n * Subscribe one workflow to the gateway's status stream and push its records\n * into the query cache.\n *\n * The hook owns no data of its own: every delivery is written to the same cache\n * entries the HTTP reads use, so components keep reading through\n * `useGaslessRequest` / `useGaslessRequestTransactions` and never learn which\n * transport produced a record. It returns only the stream's health, which the\n * caller uses to pause or resume its poll — the pattern `usePrices` uses for the\n * price feed.\n *\n * A deployment without a stream, or a disabled one, simply stays `\"idle\"`.\n *\n * @internal\n */\nexport function useGaslessRequestStream(parameters: {\n  config: Config;\n  chainId: number;\n  requestId: string;\n  service?: GaslessService;\n  enabled: boolean;\n  transport?: GaslessStatusTransport;\n}): GaslessStreamState {\n  const { config, chainId, requestId, service = \"operations\", enabled, transport = \"auto\" } = parameters;\n  const queryClient = useQueryClient();\n  const [state, setState] = useState<GaslessStreamState>({ status: \"idle\", detail: null, live: false });\n\n  const active =\n    enabled &&\n    requestId.length > 0 &&\n    transport !== \"poll\" &&\n    supportsGaslessStatusStream(config, { chainId, service });\n\n  useEffect(() => {\n    if (!active) {\n      setState({ status: \"idle\", detail: null, live: false });\n      return;\n    }\n\n    /** The same keys the query factories build, `service` and `configKey` included. */\n    const configKey = config.getChainConfigKey(chainId);\n    const requestKey = getGaslessRequestQueryKey({ chainId, requestId, service, configKey });\n    const transactionsKey = getGaslessRequestTransactionsQueryKey({ chainId, requestId, service, configKey });\n    let unwatch: (() => void) | undefined;\n\n    try {\n      unwatch = watchGaslessRequest(config, {\n        chainId,\n        requestId,\n        service,\n        onUpdate: ({ request, transactions }) => {\n          if (request) {\n            /**\n             * Cancel the poll in flight before seeding: a response that started\n             * earlier must not land on top of this fresher record.\n             */\n            void queryClient.cancelQueries({ queryKey: requestKey, exact: true });\n            queryClient.setQueryData(requestKey, (previous: GaslessRequest | undefined) =>\n              previous && isNewer(previous, request) ? previous : request,\n            );\n          }\n          if (transactions.length > 0) {\n            void queryClient.cancelQueries({ queryKey: transactionsKey, exact: true });\n            queryClient.setQueryData(transactionsKey, transactions);\n          }\n        },\n        onStatusChange: (status, detail) => setState({ status, detail, live: status === \"live\" }),\n        onError: () => {\n          /** Stream trouble is reported through the status; the poll covers the data. */\n        },\n      });\n    } catch {\n      /** An unconfigured stream is not an error here: the caller keeps polling. */\n      setState({ status: \"idle\", detail: null, live: false });\n      return;\n    }\n\n    return () => {\n      unwatch?.();\n      setState({ status: \"idle\", detail: null, live: false });\n    };\n  }, [active, config, chainId, requestId, service, queryClient]);\n\n  return state;\n}\n\n/**\n * Whether the record already in the cache is newer than an incoming one.\n *\n * A terminal status is sticky — nothing may regress it — and otherwise the\n * later `updatedAt` wins. Without this, a poll that started before a stream\n * snapshot could overwrite it with staler state.\n */\nfunction isNewer(previous: GaslessRequest, next: GaslessRequest): boolean {\n  if (isGaslessRequestTerminal(previous.status) && !isGaslessRequestTerminal(next.status)) return true;\n  if (previous.updatedAt && next.updatedAt) return previous.updatedAt > next.updatedAt;\n  return false;\n}\n"],"mappings":";;;;;AA2CA,SAAgB,EAAwB,GAOjB;CACrB,IAAM,EAAE,WAAQ,YAAS,cAAW,aAAU,cAAc,YAAS,eAAY,WAAW,GACtF,IAAc,EAAe,GAC7B,CAAC,GAAO,KAAY,EAA6B;EAAE,QAAQ;EAAQ,QAAQ;EAAM,MAAM;CAAM,CAAC,GAE9F,IACJ,KACA,EAAU,SAAS,KACnB,MAAc,UACd,EAA4B,GAAQ;EAAE;EAAS;CAAQ,CAAC;CAoD1D,OAlDA,QAAgB;EACd,IAAI,CAAC,GAAQ;GACX,EAAS;IAAE,QAAQ;IAAQ,QAAQ;IAAM,MAAM;GAAM,CAAC;GACtD;EACF;EAGA,IAAM,IAAY,EAAO,kBAAkB,CAAO,GAC5C,IAAa,EAA0B;GAAE;GAAS;GAAW;GAAS;EAAU,CAAC,GACjF,IAAkB,EAAsC;GAAE;GAAS;GAAW;GAAS;EAAU,CAAC,GACpG;EAEJ,IAAI;GACF,IAAU,EAAoB,GAAQ;IACpC;IACA;IACA;IACA,WAAW,EAAE,YAAS,sBAAmB;KAWvC,AAVI,MAKF,EAAiB,cAAc;MAAE,UAAU;MAAY,OAAO;KAAK,CAAC,GACpE,EAAY,aAAa,IAAa,MACpC,KAAY,EAAQ,GAAU,CAAO,IAAI,IAAW,CACtD,IAEE,EAAa,SAAS,MACxB,EAAiB,cAAc;MAAE,UAAU;MAAiB,OAAO;KAAK,CAAC,GACzE,EAAY,aAAa,GAAiB,CAAY;IAE1D;IACA,iBAAiB,GAAQ,MAAW,EAAS;KAAE;KAAQ;KAAQ,MAAM,MAAW;IAAO,CAAC;IACxF,eAAe,CAEf;GACF,CAAC;EACH,QAAQ;GAEN,EAAS;IAAE,QAAQ;IAAQ,QAAQ;IAAM,MAAM;GAAM,CAAC;GACtD;EACF;EAEA,aAAa;GAEX,AADA,IAAU,GACV,EAAS;IAAE,QAAQ;IAAQ,QAAQ;IAAM,MAAM;GAAM,CAAC;EACxD;CACF,GAAG;EAAC;EAAQ;EAAQ;EAAS;EAAW;EAAS;CAAW,CAAC,GAEtD;AACT;AASA,SAAS,EAAQ,GAA0B,GAA+B;CAGxE,OAFI,EAAyB,EAAS,MAAM,KAAK,CAAC,EAAyB,EAAK,MAAM,IAAU,KAC5F,EAAS,aAAa,EAAK,YAAkB,EAAS,YAAY,EAAK,YACpE;AACT"}

package/dist/gasless/use-gasless-request-transactions.d.ts

@@ -0,0 +1,42 @@
+import { ConfigParameter, GetGaslessRequestTransactionsOptions, GetGaslessRequestTransactionsReturnType } from '@symmio/trading-core';
+import { UseQueryResult } from '@tanstack/react-query';
+import { SymmioRequestError } from '../errors/symmio-request-error.js';
+/** Parameters for {@link useGaslessRequestTransactions}. */
+export type UseGaslessRequestTransactionsParameters = GetGaslessRequestTransactionsOptions & ConfigParameter;
+/** Return type of {@link useGaslessRequestTransactions}. */
+export type UseGaslessRequestTransactionsReturnType = UseQueryResult<GetGaslessRequestTransactionsReturnType, SymmioRequestError>;
+/**
+ * List the EVM broadcast attempts stored for one GaslessQ request.
+ *
+ * The companion to {@link useGaslessRequest}: the record says what the workflow
+ * is doing, this says which transactions it tried. That distinction is
+ * load-bearing — the relayer replaces a stuck transaction, so a request has one
+ * id and possibly several hashes, and an attempt that `reverted` or `failed`
+ * does not mean the request did. Read the outcome from the record; read the
+ * attempts to link to an explorer or to explain a failure.
+ *
+ * **Polls only when you pass the record's `status`.** The attempts list has no
+ * terminal of its own to stop on, so a self-driven poll would outlive the
+ * workflow. Hand it the status you are already reading from `useGaslessRequest`
+ * and it follows the same jittered cadence and stops when the record does;
+ * leave it out and it fetches once, with `query.refetchInterval` yours to set.
+ *
+ * Enabled only while `requestId` is non-empty, so the hook can mount before a
+ * submit has happened.
+ *
+ * @param parameters - Request id, the optional cadence `status`, optional service and chain id, TanStack overrides.
+ * @returns The stored attempts, oldest first as the service returns them.
+ *
+ * @example
+ * ```tsx
+ * const request = useGaslessRequest({ requestId: requestId ?? "", query: { enabled: Boolean(requestId) } });
+ * const attempts = useGaslessRequestTransactions({
+ *   requestId: requestId ?? "",
+ *   status: request.data?.status,
+ *   query: { enabled: Boolean(requestId) },
+ * });
+ * const latest = attempts.data?.at(-1);
+ * ```
+ */
+export declare function useGaslessRequestTransactions(parameters: UseGaslessRequestTransactionsParameters): UseGaslessRequestTransactionsReturnType;
+//# sourceMappingURL=use-gasless-request-transactions.d.ts.map

package/dist/gasless/use-gasless-request-transactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gasless-request-transactions.d.ts","sourceRoot":"","sources":["../../src/gasless/use-gasless-request-transactions.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,oCAAoC,EACzC,KAAK,uCAAuC,EAC7C,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,4DAA4D;AAC5D,MAAM,MAAM,uCAAuC,GAAG,oCAAoC,GAAG,eAAe,CAAC;AAE7G,4DAA4D;AAC5D,MAAM,MAAM,uCAAuC,GAAG,cAAc,CAClE,uCAAuC,EACvC,kBAAkB,CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,uCAAuC,GAClD,uCAAuC,CAoBzC"}

package/dist/gasless/use-gasless-request-transactions.js

@@ -0,0 +1,28 @@
+"use client";
+import { useSymmioChainId as e } from "../provider/use-symmio-chain-id.js";
+import { useSymmioConfig as t } from "../provider/use-symmio-config.js";
+import { normalizeSymmError as n } from "../errors/normalize-symm-error.js";
+import { getGaslessRequestTransactionsQueryOptions as r } from "@symmio/trading-core";
+import { useQuery as i } from "@tanstack/react-query";
+//#region src/gasless/use-gasless-request-transactions.ts
+function a(a) {
+	let o = t(a), s = e(), c = r(o, {
+		...a,
+		chainId: a.chainId ?? s
+	});
+	return i({
+		...c,
+		enabled: (a.query?.enabled ?? !0) && a.requestId.length > 0,
+		queryFn: async (e) => {
+			try {
+				return await c.queryFn(e);
+			} catch (e) {
+				throw n(e);
+			}
+		}
+	});
+}
+//#endregion
+export { a as useGaslessRequestTransactions };
+
+//# sourceMappingURL=use-gasless-request-transactions.js.map

package/dist/gasless/use-gasless-request-transactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gasless-request-transactions.js","names":[],"sources":["../../src/gasless/use-gasless-request-transactions.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  getGaslessRequestTransactionsQueryOptions,\n  type ConfigParameter,\n  type GetGaslessRequestTransactionsOptions,\n  type GetGaslessRequestTransactionsReturnType,\n} from \"@symmio/trading-core\";\nimport { useQuery, type UseQueryResult } from \"@tanstack/react-query\";\nimport { normalizeSymmError } from \"../errors/normalize-symm-error\";\nimport type { SymmioRequestError } from \"../errors/symmio-request-error\";\nimport { useSymmioChainId } from \"../provider/use-symmio-chain-id\";\nimport { useSymmioConfig } from \"../provider/use-symmio-config\";\n\n/** Parameters for {@link useGaslessRequestTransactions}. */\nexport type UseGaslessRequestTransactionsParameters = GetGaslessRequestTransactionsOptions & ConfigParameter;\n\n/** Return type of {@link useGaslessRequestTransactions}. */\nexport type UseGaslessRequestTransactionsReturnType = UseQueryResult<\n  GetGaslessRequestTransactionsReturnType,\n  SymmioRequestError\n>;\n\n/**\n * List the EVM broadcast attempts stored for one GaslessQ request.\n *\n * The companion to {@link useGaslessRequest}: the record says what the workflow\n * is doing, this says which transactions it tried. That distinction is\n * load-bearing — the relayer replaces a stuck transaction, so a request has one\n * id and possibly several hashes, and an attempt that `reverted` or `failed`\n * does not mean the request did. Read the outcome from the record; read the\n * attempts to link to an explorer or to explain a failure.\n *\n * **Polls only when you pass the record's `status`.** The attempts list has no\n * terminal of its own to stop on, so a self-driven poll would outlive the\n * workflow. Hand it the status you are already reading from `useGaslessRequest`\n * and it follows the same jittered cadence and stops when the record does;\n * leave it out and it fetches once, with `query.refetchInterval` yours to set.\n *\n * Enabled only while `requestId` is non-empty, so the hook can mount before a\n * submit has happened.\n *\n * @param parameters - Request id, the optional cadence `status`, optional service and chain id, TanStack overrides.\n * @returns The stored attempts, oldest first as the service returns them.\n *\n * @example\n * ```tsx\n * const request = useGaslessRequest({ requestId: requestId ?? \"\", query: { enabled: Boolean(requestId) } });\n * const attempts = useGaslessRequestTransactions({\n *   requestId: requestId ?? \"\",\n *   status: request.data?.status,\n *   query: { enabled: Boolean(requestId) },\n * });\n * const latest = attempts.data?.at(-1);\n * ```\n */\nexport function useGaslessRequestTransactions(\n  parameters: UseGaslessRequestTransactionsParameters,\n): UseGaslessRequestTransactionsReturnType {\n  const config = useSymmioConfig(parameters);\n  const chainId = useSymmioChainId();\n\n  const options = getGaslessRequestTransactionsQueryOptions(config, {\n    ...parameters,\n    chainId: parameters.chainId ?? chainId,\n  });\n\n  return useQuery({\n    ...options,\n    enabled: (parameters.query?.enabled ?? true) && parameters.requestId.length > 0,\n    queryFn: async (context) => {\n      try {\n        return await options.queryFn(context);\n      } catch (err) {\n        throw normalizeSymmError(err);\n      }\n    },\n  }) as UseGaslessRequestTransactionsReturnType;\n}\n"],"mappings":";;;;;;;AAwDA,SAAgB,EACd,GACyC;CACzC,IAAM,IAAS,EAAgB,CAAU,GACnC,IAAU,EAAiB,GAE3B,IAAU,EAA0C,GAAQ;EAChE,GAAG;EACH,SAAS,EAAW,WAAW;CACjC,CAAC;CAED,OAAO,EAAS;EACd,GAAG;EACH,UAAU,EAAW,OAAO,WAAW,OAAS,EAAW,UAAU,SAAS;EAC9E,SAAS,OAAO,MAAY;GAC1B,IAAI;IACF,OAAO,MAAM,EAAQ,QAAQ,CAAO;GACtC,SAAS,GAAK;IACZ,MAAM,EAAmB,CAAG;GAC9B;EACF;CACF,CAAC;AACH"}

package/dist/gasless/use-gasless-request.d.ts

@@ -0,0 +1,56 @@
+import { ConfigParameter, GaslessStatusTransport, GetGaslessRequestOptions, GetGaslessRequestReturnType } from '@symmio/trading-core';
+import { UseQueryResult } from '@tanstack/react-query';
+import { SymmioRequestError } from '../errors/symmio-request-error.js';
+import { GaslessStreamState } from './use-gasless-request-stream.js';
+/** Parameters for {@link useGaslessRequest}. */
+export type UseGaslessRequestParameters = GetGaslessRequestOptions & ConfigParameter & {
+    /**
+     * Invalidate account-balance reads once the request transitions to
+     * `succeeded` (a relayed operation moved collateral: the action itself
+     * and/or its operational fee). Default `true`. Flow-specific reads are the
+     * submitting hook's job — this covers the balance staleness every gasless
+     * success implies.
+     */
+    invalidateOnSuccess?: boolean;
+    /**
+     * How to follow the workflow. `"auto"` (default) subscribes to the
+     * gateway's status stream where the deployment enables it and polls only
+     * while the stream is not delivering; `"poll"` forces HTTP polling.
+     */
+    transport?: GaslessStatusTransport;
+};
+/** Return type of {@link useGaslessRequest}. */
+export type UseGaslessRequestReturnType = UseQueryResult<GetGaslessRequestReturnType, SymmioRequestError> & {
+    /**
+     * The live transport's health. `stream.live` means the record is arriving
+     * over the WebSocket and this hook has stopped polling; anything else means
+     * it is polling, which is also the whole behavior on a deployment without a
+     * status stream.
+     */
+    stream: GaslessStreamState;
+};
+/**
+ * Poll one GaslessQ relayer request.
+ *
+ * **Polls on its own.** The query factory ships the service-recommended cadence
+ * — a jittered 1–2 s while `queued`, 3–5 s after `submitted`, stopping at a
+ * terminal status — tolerates the brief post-`202` `404` while the record
+ * becomes readable, and absorbs transient transport failures (`429`, `503`, a
+ * dropped connection) with the gateway's `Retry-After` when it sent one. A
+ * failed read is not a failed request, so none of that surfaces as an error.
+ * Pass `query.refetchInterval` only to override the cadence.
+ *
+ * Enabled only while `requestId` is non-empty, so the hook can mount before a
+ * submit has happened. `submitted` is **not** success; only `succeeded` is.
+ *
+ * On a `succeeded` terminal it invalidates account balances (every relayed
+ * action moves collateral); pass `invalidateOnSuccess: false` to opt out. Reads
+ * specific to the action belong to the hook that submitted it.
+ *
+ * @example
+ * ```tsx
+ * const request = useGaslessRequest({ requestId: requestId ?? "", query: { enabled: Boolean(requestId) } });
+ * ```
+ */
+export declare function useGaslessRequest(parameters: UseGaslessRequestParameters): UseGaslessRequestReturnType;
+//# sourceMappingURL=use-gasless-request.d.ts.map

package/dist/gasless/use-gasless-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gasless-request.d.ts","sourceRoot":"","sources":["../../src/gasless/use-gasless-request.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EACjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGtF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEhG,gDAAgD;AAChD,MAAM,MAAM,2BAA2B,GAAG,wBAAwB,GAChE,eAAe,GAAG;IAChB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC,CAAC;AAEJ,gDAAgD;AAChD,MAAM,MAAM,2BAA2B,GAAG,cAAc,CAAC,2BAA2B,EAAE,kBAAkB,CAAC,GAAG;IAC1G;;;;;OAKG;IACH,MAAM,EAAE,kBAAkB,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,2BAA2B,GAAG,2BAA2B,CA+DtG"}

package/dist/gasless/use-gasless-request.js

@@ -0,0 +1,51 @@
+"use client";
+import { useSymmioChainId as e } from "../provider/use-symmio-chain-id.js";
+import { useSymmioConfig as t } from "../provider/use-symmio-config.js";
+import { normalizeSymmError as n } from "../errors/normalize-symm-error.js";
+import { invalidateAccountBalances as r } from "../utils/invalidate-account-balances.js";
+import { useGaslessRequestStream as i } from "./use-gasless-request-stream.js";
+import { GaslessRequestStatus as a, getGaslessRequestQueryOptions as o } from "@symmio/trading-core";
+import { useEffect as s, useRef as c } from "react";
+import { useQuery as l, useQueryClient as u } from "@tanstack/react-query";
+//#region src/gasless/use-gasless-request.ts
+function d(d) {
+	let f = t(d), p = e(), m = u(), h = d.chainId ?? p, { invalidateOnSuccess: g = !0, transport: _ = "auto", ...v } = d, y = i({
+		config: f,
+		chainId: h,
+		requestId: d.requestId,
+		service: d.service,
+		enabled: (d.query?.enabled ?? !0) && d.requestId.length > 0,
+		transport: _
+	}), b = o(f, {
+		...v,
+		chainId: h
+	}), x = l({
+		...b,
+		enabled: (d.query?.enabled ?? !0) && d.requestId.length > 0,
+		refetchInterval: d.query?.refetchInterval ?? (y.live ? !1 : b.refetchInterval),
+		queryFn: async (e) => {
+			try {
+				return await b.queryFn(e);
+			} catch (e) {
+				throw n(e);
+			}
+		}
+	}), S = c(null), C = x.data?.status;
+	return s(() => {
+		!g || C !== a.SUCCEEDED || S.current !== d.requestId && (S.current = d.requestId, r(m, { configKey: f.getChainConfigKey(h) }));
+	}, [
+		g,
+		C,
+		d.requestId,
+		m,
+		f,
+		h
+	]), {
+		...x,
+		stream: y
+	};
+}
+//#endregion
+export { d as useGaslessRequest };
+
+//# sourceMappingURL=use-gasless-request.js.map

package/dist/gasless/use-gasless-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gasless-request.js","names":[],"sources":["../../src/gasless/use-gasless-request.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  GaslessRequestStatus,\n  getGaslessRequestQueryOptions,\n  type ConfigParameter,\n  type GaslessStatusTransport,\n  type GetGaslessRequestOptions,\n  type GetGaslessRequestReturnType,\n} from \"@symmio/trading-core\";\nimport { useQuery, useQueryClient, type UseQueryResult } from \"@tanstack/react-query\";\nimport { useEffect, useRef } from \"react\";\nimport { normalizeSymmError } from \"../errors/normalize-symm-error\";\nimport type { SymmioRequestError } from \"../errors/symmio-request-error\";\nimport { useSymmioChainId } from \"../provider/use-symmio-chain-id\";\nimport { useSymmioConfig } from \"../provider/use-symmio-config\";\nimport { invalidateAccountBalances } from \"../utils/invalidate-account-balances\";\nimport { useGaslessRequestStream, type GaslessStreamState } from \"./use-gasless-request-stream\";\n\n/** Parameters for {@link useGaslessRequest}. */\nexport type UseGaslessRequestParameters = GetGaslessRequestOptions &\n  ConfigParameter & {\n    /**\n     * Invalidate account-balance reads once the request transitions to\n     * `succeeded` (a relayed operation moved collateral: the action itself\n     * and/or its operational fee). Default `true`. Flow-specific reads are the\n     * submitting hook's job — this covers the balance staleness every gasless\n     * success implies.\n     */\n    invalidateOnSuccess?: boolean;\n    /**\n     * How to follow the workflow. `\"auto\"` (default) subscribes to the\n     * gateway's status stream where the deployment enables it and polls only\n     * while the stream is not delivering; `\"poll\"` forces HTTP polling.\n     */\n    transport?: GaslessStatusTransport;\n  };\n\n/** Return type of {@link useGaslessRequest}. */\nexport type UseGaslessRequestReturnType = UseQueryResult<GetGaslessRequestReturnType, SymmioRequestError> & {\n  /**\n   * The live transport's health. `stream.live` means the record is arriving\n   * over the WebSocket and this hook has stopped polling; anything else means\n   * it is polling, which is also the whole behavior on a deployment without a\n   * status stream.\n   */\n  stream: GaslessStreamState;\n};\n\n/**\n * Poll one GaslessQ relayer request.\n *\n * **Polls on its own.** The query factory ships the service-recommended cadence\n * — a jittered 1–2 s while `queued`, 3–5 s after `submitted`, stopping at a\n * terminal status — tolerates the brief post-`202` `404` while the record\n * becomes readable, and absorbs transient transport failures (`429`, `503`, a\n * dropped connection) with the gateway's `Retry-After` when it sent one. A\n * failed read is not a failed request, so none of that surfaces as an error.\n * Pass `query.refetchInterval` only to override the cadence.\n *\n * Enabled only while `requestId` is non-empty, so the hook can mount before a\n * submit has happened. `submitted` is **not** success; only `succeeded` is.\n *\n * On a `succeeded` terminal it invalidates account balances (every relayed\n * action moves collateral); pass `invalidateOnSuccess: false` to opt out. Reads\n * specific to the action belong to the hook that submitted it.\n *\n * @example\n * ```tsx\n * const request = useGaslessRequest({ requestId: requestId ?? \"\", query: { enabled: Boolean(requestId) } });\n * ```\n */\nexport function useGaslessRequest(parameters: UseGaslessRequestParameters): UseGaslessRequestReturnType {\n  const config = useSymmioConfig(parameters);\n  const chainId = useSymmioChainId();\n  const queryClient = useQueryClient();\n  const resolvedChainId = parameters.chainId ?? chainId;\n  /**\n   * Strip the hook-only control flag before forwarding: the key factory hashes\n   * whatever it is handed, so leaving it in would make two callers watching the\n   * same request with different flags key on separate cache entries and poll\n   * the record twice.\n   */\n  const { invalidateOnSuccess = true, transport = \"auto\", ...queryParameters } = parameters;\n\n  /**\n   * The stream writes straight into this hook's cache entry, so the query below\n   * only has to stop polling while it is live.\n   */\n  const stream = useGaslessRequestStream({\n    config,\n    chainId: resolvedChainId,\n    requestId: parameters.requestId,\n    service: parameters.service,\n    enabled: (parameters.query?.enabled ?? true) && parameters.requestId.length > 0,\n    transport,\n  });\n\n  const options = getGaslessRequestQueryOptions(config, {\n    ...queryParameters,\n    chainId: resolvedChainId,\n  });\n\n  const result = useQuery({\n    ...options,\n    enabled: (parameters.query?.enabled ?? true) && parameters.requestId.length > 0,\n    /**\n     * While the stream delivers, polling stands down; an explicit\n     * `query.refetchInterval` still wins, and a degraded stream resumes it.\n     */\n    refetchInterval: parameters.query?.refetchInterval ?? (stream.live ? false : options.refetchInterval),\n    queryFn: async (context) => {\n      try {\n        /** Forwards TanStack's abort signal, so an unmounted poll stops in flight. */\n        return await options.queryFn(context);\n      } catch (err) {\n        throw normalizeSymmError(err);\n      }\n    },\n  }) as UseGaslessRequestReturnType;\n\n  /**\n   * Invalidate balances exactly once per request id on the transition into\n   * `succeeded` — after on-chain reality, per the invalidation timing rule.\n   */\n  const invalidatedForRef = useRef<string | null>(null);\n  const status = result.data?.status;\n  useEffect(() => {\n    if (!invalidateOnSuccess || status !== GaslessRequestStatus.SUCCEEDED) return;\n    if (invalidatedForRef.current === parameters.requestId) return;\n    invalidatedForRef.current = parameters.requestId;\n    invalidateAccountBalances(queryClient, { configKey: config.getChainConfigKey(resolvedChainId) });\n  }, [invalidateOnSuccess, status, parameters.requestId, queryClient, config, resolvedChainId]);\n\n  return { ...result, stream } as UseGaslessRequestReturnType;\n}\n"],"mappings":";;;;;;;;;;AAwEA,SAAgB,EAAkB,GAAsE;CACtG,IAAM,IAAS,EAAgB,CAAU,GACnC,IAAU,EAAiB,GAC3B,IAAc,EAAe,GAC7B,IAAkB,EAAW,WAAW,GAOxC,EAAE,yBAAsB,IAAM,eAAY,QAAQ,GAAG,MAAoB,GAMzE,IAAS,EAAwB;EACrC;EACA,SAAS;EACT,WAAW,EAAW;EACtB,SAAS,EAAW;EACpB,UAAU,EAAW,OAAO,WAAW,OAAS,EAAW,UAAU,SAAS;EAC9E;CACF,CAAC,GAEK,IAAU,EAA8B,GAAQ;EACpD,GAAG;EACH,SAAS;CACX,CAAC,GAEK,IAAS,EAAS;EACtB,GAAG;EACH,UAAU,EAAW,OAAO,WAAW,OAAS,EAAW,UAAU,SAAS;EAK9E,iBAAiB,EAAW,OAAO,oBAAoB,EAAO,OAAO,KAAQ,EAAQ;EACrF,SAAS,OAAO,MAAY;GAC1B,IAAI;IAEF,OAAO,MAAM,EAAQ,QAAQ,CAAO;GACtC,SAAS,GAAK;IACZ,MAAM,EAAmB,CAAG;GAC9B;EACF;CACF,CAAC,GAMK,IAAoB,EAAsB,IAAI,GAC9C,IAAS,EAAO,MAAM;CAQ5B,OAPA,QAAgB;EACV,CAAC,KAAuB,MAAW,EAAqB,aACxD,EAAkB,YAAY,EAAW,cAC7C,EAAkB,UAAU,EAAW,WACvC,EAA0B,GAAa,EAAE,WAAW,EAAO,kBAAkB,CAAe,EAAE,CAAC;CACjG,GAAG;EAAC;EAAqB;EAAQ,EAAW;EAAW;EAAa;EAAQ;CAAe,CAAC,GAErF;EAAE,GAAG;EAAQ;CAAO;AAC7B"}

package/dist/gasless/use-gasless-wallet-address.d.ts

@@ -0,0 +1,24 @@
+import { ConfigParameter, GetGaslessWalletAddressOptions, GetGaslessWalletAddressReturnType } from '@symmio/trading-core';
+import { UseQueryResult } from '@tanstack/react-query';
+import { SymmioRequestError } from '../errors/symmio-request-error.js';
+/** Parameters for {@link useGaslessWalletAddress}. */
+export type UseGaslessWalletAddressParameters = GetGaslessWalletAddressOptions & ConfigParameter;
+/** Return type of {@link useGaslessWalletAddress}. */
+export type UseGaslessWalletAddressReturnType = UseQueryResult<GetGaslessWalletAddressReturnType, SymmioRequestError>;
+/**
+ * Read the deterministic address of one of an owner's GaslessWallets (a pure
+ * CREATE2 view on the GaslessLayer) - the deposit address for gasless
+ * onboarding and the target of gasless-wallet operations. A wallet is
+ * identified by `(owner, walletId)`; `walletId` defaults to `0n`, the original
+ * wallet, and each positive id has its own address.
+ *
+ * @param parameters - Owner, optional `walletId` (default `0n`), optional chain id, config and query overrides.
+ * @returns The TanStack query result, with failures normalized to {@link SymmioRequestError}.
+ *
+ * @example
+ * ```tsx
+ * const query = useGaslessWalletAddress({ owner, walletId: 1n });
+ * ```
+ */
+export declare function useGaslessWalletAddress(parameters: UseGaslessWalletAddressParameters): UseGaslessWalletAddressReturnType;
+//# sourceMappingURL=use-gasless-wallet-address.d.ts.map

package/dist/gasless/use-gasless-wallet-address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gasless-wallet-address.d.ts","sourceRoot":"","sources":["../../src/gasless/use-gasless-wallet-address.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,8BAA8B,EACnC,KAAK,iCAAiC,EACvC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,sDAAsD;AACtD,MAAM,MAAM,iCAAiC,GAAG,8BAA8B,GAAG,eAAe,CAAC;AAEjG,sDAAsD;AACtD,MAAM,MAAM,iCAAiC,GAAG,cAAc,CAAC,iCAAiC,EAAE,kBAAkB,CAAC,CAAC;AAEtH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,iCAAiC,GAC5C,iCAAiC,CAmBnC"}

package/dist/gasless/use-gasless-wallet-address.js

@@ -0,0 +1,27 @@
+"use client";
+import { useSymmioChainId as e } from "../provider/use-symmio-chain-id.js";
+import { useSymmioConfig as t } from "../provider/use-symmio-config.js";
+import { normalizeSymmError as n } from "../errors/normalize-symm-error.js";
+import { getGaslessWalletAddressQueryOptions as r } from "@symmio/trading-core";
+import { useQuery as i } from "@tanstack/react-query";
+//#region src/gasless/use-gasless-wallet-address.ts
+function a(a) {
+	let o = t(a), s = e(), c = r(o, {
+		...a,
+		chainId: a.chainId ?? s
+	});
+	return i({
+		...c,
+		queryFn: async () => {
+			try {
+				return await c.queryFn();
+			} catch (e) {
+				throw n(e);
+			}
+		}
+	});
+}
+//#endregion
+export { a as useGaslessWalletAddress };
+
+//# sourceMappingURL=use-gasless-wallet-address.js.map

package/dist/gasless/use-gasless-wallet-address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gasless-wallet-address.js","names":[],"sources":["../../src/gasless/use-gasless-wallet-address.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  getGaslessWalletAddressQueryOptions,\n  type ConfigParameter,\n  type GetGaslessWalletAddressOptions,\n  type GetGaslessWalletAddressReturnType,\n} from \"@symmio/trading-core\";\nimport { useQuery, type UseQueryResult } from \"@tanstack/react-query\";\nimport { normalizeSymmError } from \"../errors/normalize-symm-error\";\nimport type { SymmioRequestError } from \"../errors/symmio-request-error\";\nimport { useSymmioChainId } from \"../provider/use-symmio-chain-id\";\nimport { useSymmioConfig } from \"../provider/use-symmio-config\";\n\n/** Parameters for {@link useGaslessWalletAddress}. */\nexport type UseGaslessWalletAddressParameters = GetGaslessWalletAddressOptions & ConfigParameter;\n\n/** Return type of {@link useGaslessWalletAddress}. */\nexport type UseGaslessWalletAddressReturnType = UseQueryResult<GetGaslessWalletAddressReturnType, SymmioRequestError>;\n\n/**\n * Read the deterministic address of one of an owner's GaslessWallets (a pure\n * CREATE2 view on the GaslessLayer) - the deposit address for gasless\n * onboarding and the target of gasless-wallet operations. A wallet is\n * identified by `(owner, walletId)`; `walletId` defaults to `0n`, the original\n * wallet, and each positive id has its own address.\n *\n * @param parameters - Owner, optional `walletId` (default `0n`), optional chain id, config and query overrides.\n * @returns The TanStack query result, with failures normalized to {@link SymmioRequestError}.\n *\n * @example\n * ```tsx\n * const query = useGaslessWalletAddress({ owner, walletId: 1n });\n * ```\n */\nexport function useGaslessWalletAddress(\n  parameters: UseGaslessWalletAddressParameters,\n): UseGaslessWalletAddressReturnType {\n  const config = useSymmioConfig(parameters);\n  const chainId = useSymmioChainId();\n\n  const options = getGaslessWalletAddressQueryOptions(config, {\n    ...parameters,\n    chainId: parameters.chainId ?? chainId,\n  });\n\n  return useQuery({\n    ...options,\n    queryFn: async () => {\n      try {\n        return await options.queryFn();\n      } catch (err) {\n        throw normalizeSymmError(err);\n      }\n    },\n  }) as UseGaslessWalletAddressReturnType;\n}\n"],"mappings":";;;;;;;AAmCA,SAAgB,EACd,GACmC;CACnC,IAAM,IAAS,EAAgB,CAAU,GACnC,IAAU,EAAiB,GAE3B,IAAU,EAAoC,GAAQ;EAC1D,GAAG;EACH,SAAS,EAAW,WAAW;CACjC,CAAC;CAED,OAAO,EAAS;EACd,GAAG;EACH,SAAS,YAAY;GACnB,IAAI;IACF,OAAO,MAAM,EAAQ,QAAQ;GAC/B,SAAS,GAAK;IACZ,MAAM,EAAmB,CAAG;GAC9B;EACF;CACF,CAAC;AACH"}

package/dist/gasless/use-gasless-wallet-creation-fee.d.ts

@@ -0,0 +1,29 @@
+import { ConfigParameter, GetGaslessWalletCreationFeeOptions, GetGaslessWalletCreationFeeReturnType } from '@symmio/trading-core';
+import { UseQueryResult } from '@tanstack/react-query';
+import { SymmioRequestError } from '../errors/symmio-request-error.js';
+/** Parameters for {@link useGaslessWalletCreationFee}. */
+export type UseGaslessWalletCreationFeeParameters = GetGaslessWalletCreationFeeOptions & ConfigParameter;
+/** Return type of {@link useGaslessWalletCreationFee}. */
+export type UseGaslessWalletCreationFeeReturnType = UseQueryResult<GetGaslessWalletCreationFeeReturnType, SymmioRequestError>;
+/**
+ * Read the one-time fee for deploying one of an owner's GaslessWallets
+ * (`getWalletCreationFee(owner, walletId)` on the GaslessLayer), in collateral
+ * token units. It is the configured fee while the wallet has no code, for any
+ * wallet id including `0`, and `0n` once the wallet is deployed. A deposit
+ * settlement deducts it from the swept balance; a relayed wallet operation
+ * charges it to the payer's SYMMIO balance.
+ *
+ * The relay hooks invalidate it after a wallet execute or a deposit settlement,
+ * since either may deploy the wallet.
+ *
+ * @param parameters - Owner, optional `walletId` (default `0n`), optional chain id, config and query overrides.
+ * @returns The TanStack query result, with failures normalized to {@link SymmioRequestError}.
+ *
+ * @example
+ * ```tsx
+ * const creationFee = useGaslessWalletCreationFee({ owner, walletId: 1n });
+ * const chargesFirstUse = (creationFee.data ?? 0n) > 0n;
+ * ```
+ */
+export declare function useGaslessWalletCreationFee(parameters: UseGaslessWalletCreationFeeParameters): UseGaslessWalletCreationFeeReturnType;
+//# sourceMappingURL=use-gasless-wallet-creation-fee.d.ts.map

package/dist/gasless/use-gasless-wallet-creation-fee.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-gasless-wallet-creation-fee.d.ts","sourceRoot":"","sources":["../../src/gasless/use-gasless-wallet-creation-fee.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,kCAAkC,EACvC,KAAK,qCAAqC,EAC3C,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,0DAA0D;AAC1D,MAAM,MAAM,qCAAqC,GAAG,kCAAkC,GAAG,eAAe,CAAC;AAEzG,0DAA0D;AAC1D,MAAM,MAAM,qCAAqC,GAAG,cAAc,CAChE,qCAAqC,EACrC,kBAAkB,CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,qCAAqC,GAChD,qCAAqC,CAmBvC"}