@pegaroute/sdk 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,901 @@
+import { a as toExternalStatus, i as isTerminalStatus, n as isExecutionMode, r as hasQuoteRouteFees, t as isExecutionFamily } from "./types-Dt7OyLsD.js";
+//#region src/core/errors.ts
+/** Base class for every error the SDK throws after a request is made. */
+var PegarouteError = class extends Error {
+	/** Machine-readable error code, e.g. `QUOTE_EXPIRED`. */
+	code;
+	/** HTTP status, or `null` when no response was received. */
+	status;
+	/** Safe to show to end users. */
+	userMessage;
+	/**
+	* Whether the same request may succeed if tried again.
+	* The SDK retries such GETs itself, up to `maxRetries` times, unless the server asks to wait more than 60 seconds.
+	* POSTs are never retried, so retrying one is up to you.
+	*/
+	retryable;
+	/** Seconds the server asked us to wait before retrying, or `null` when it didn't say. */
+	retryAfterSeconds;
+	/** Provider that caused the error, when the failure is provider-specific. */
+	provider;
+	/** Extra context from the server (or the SDK) about the failure. */
+	details;
+	constructor(init) {
+		super(init.message, init.cause === void 0 ? void 0 : { cause: init.cause });
+		this.name = new.target.name;
+		this.code = init.code;
+		this.status = init.status;
+		this.userMessage = init.userMessage;
+		this.retryable = init.retryable;
+		this.retryAfterSeconds = init.retryAfterSeconds ?? null;
+		if (init.provider !== void 0) this.provider = init.provider;
+		if (init.details !== void 0) this.details = init.details;
+	}
+};
+/** The request is invalid, e.g. a bad address, amount or unsupported pair (HTTP 400). */
+var BadRequestError = class extends PegarouteError {};
+/** The API key is missing or invalid (HTTP 401). */
+var AuthenticationError = class extends PegarouteError {};
+/** The API key isn't allowed to make this request (HTTP 403). */
+var PermissionDeniedError = class extends PegarouteError {};
+/** The resource doesn't exist, e.g. an unknown swap ID (HTTP 404). */
+var NotFoundError = class extends PegarouteError {};
+/** The request conflicts with the current state (HTTP 409). See {@link ProviderChangedError} for a changed provider. */
+var ConflictError = class extends PegarouteError {};
+/**
+* The quoted route is no longer available, so Pegaroute quoted again (HTTP 409, `PROVIDER_CHANGED`).
+* The original `quoteId` is used up: show the user `newQuote` and call `swaps.create` again with its `quoteId`.
+*
+* @example
+* catch (e) {
+*   if (e instanceof ProviderChangedError) retryWith(e.newQuote);
+* }
+*/
+var ProviderChangedError = class extends ConflictError {
+	/** The refreshed quote to review and retry with. */
+	newQuote;
+	/** The provider that was quoted (or requested with `routeProvider`). */
+	originalProvider;
+	/** The best provider under the refreshed quote. */
+	newProvider;
+	constructor(init) {
+		super(init);
+		this.newQuote = init.newQuote;
+		this.originalProvider = init.originalProvider;
+		this.newProvider = init.newProvider;
+	}
+};
+/** The quote is no longer valid; request a new one. */
+var QuoteExpiredError = class extends PegarouteError {};
+/** The request is well-formed but can't be carried out, e.g. the memo is too long (HTTP 422). */
+var UnprocessableEntityError = class extends PegarouteError {};
+/** Too many requests (HTTP 429). `retryAfterSeconds` says how long to wait, when the server sends it. */
+var RateLimitError = class extends PegarouteError {};
+/** A chain is halted or disabled, or a provider is down. */
+var ServiceUnavailableError = class extends PegarouteError {};
+/** Pegaroute, a provider or a gateway in front of it failed (HTTP 500, 502, 504 or another 5xx except 503). */
+var InternalServerError = class extends PegarouteError {};
+/**
+* No complete response was received: the connection failed (DNS, TCP, TLS, …) or dropped mid-response.
+* `status` is `null` unless the failure happened while reading the body.
+*/
+var ConnectionError = class extends PegarouteError {};
+/** The request did not complete within the configured timeout. */
+var TimeoutError = class extends ConnectionError {};
+/**
+* `swaps.waitForCompletion` reached its `timeoutMs` before the swap reached a terminal status (code `WAIT_TIMEOUT`).
+*
+* The swap itself didn't fail: it may still finish, so check it again later (or wait for its webhook).
+* Not a `TimeoutError`, which means a single HTTP request timed out.
+*
+* @example
+* catch (e) {
+*   if (e instanceof WaitTimeoutError) console.log("still", e.lastSwap?.status);
+* }
+*/
+var WaitTimeoutError = class extends PegarouteError {
+	/** The most recent successful poll, or `null` if the deadline passed before the first one returned. */
+	lastSwap;
+	constructor(init) {
+		super(init);
+		this.lastSwap = init.lastSwap;
+	}
+};
+/**
+* Error classes that map to exactly one HTTP status.
+*
+* Not listed here on purpose:
+* - `InternalServerError` covers a range (500, 502, 504, other 5xx) — see {@link errorClassForStatus}.
+* - `ConnectionError` / `TimeoutError` can't be looked up by status because no response arrived; the HTTP client
+*   creates them directly. They still extend `PegarouteError` (with `status: null`).
+* - `ProviderChangedError` shares 409 with `ConflictError`; {@link errorFromResponse} picks it by the error code
+*   `PROVIDER_CHANGED` (and only when the body carries the refreshed quote).
+* - `WaitTimeoutError` isn't an HTTP failure at all: `swaps.waitForCompletion` throws it when its own deadline
+*   passes (also `status: null`).
+* - Any other status (e.g. 413) falls back to the base `PegarouteError`.
+*/
+const ERROR_CLASS_BY_STATUS = {
+	400: BadRequestError,
+	401: AuthenticationError,
+	403: PermissionDeniedError,
+	404: NotFoundError,
+	409: ConflictError,
+	410: QuoteExpiredError,
+	422: UnprocessableEntityError,
+	429: RateLimitError,
+	503: ServiceUnavailableError
+};
+/**
+* Statuses worth trying again when the error body doesn't say: rate limited, or a temporary gateway or availability
+* failure (often a proxy's own error page, without Pegaroute's error envelope).
+*/
+const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+	429,
+	502,
+	503,
+	504
+]);
+/** Exact status match first, then any other 5xx → `InternalServerError`, otherwise the base class. */
+function errorClassForStatus(status) {
+	return ERROR_CLASS_BY_STATUS[status] ?? (status >= 500 ? InternalServerError : PegarouteError);
+}
+/** Checks that a parsed body looks like an {@link PegarouteErrorEnvelope} (e.g. not a proxy's HTML error page). */
+function isPegarouteErrorEnvelope(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const error = value.error;
+	if (typeof error !== "object" || error === null) return false;
+	const { code, message } = error;
+	return typeof code === "string" && typeof message === "string";
+}
+/** Checks that a 409 body carries the refreshed quote and both provider names. */
+function isProviderChangedBody(value) {
+	const { newQuote, originalProvider, newProvider } = value;
+	return typeof newQuote === "object" && newQuote !== null && typeof originalProvider === "string" && typeof newProvider === "string";
+}
+/**
+* Builds the matching error subclass from a non-2xx response and its (already read) body text.
+*
+* `retryable` is the server's own flag when its error body has one, otherwise it follows RETRYABLE_STATUSES. The HTTP client retries a GET only when it is `true`, so callers see the same answer the SDK acted on.
+*/
+function errorFromResponse(response, bodyText) {
+	const ErrorClass = errorClassForStatus(response.status);
+	let body;
+	try {
+		body = JSON.parse(bodyText);
+	} catch {
+		body = void 0;
+	}
+	if (!isPegarouteErrorEnvelope(body)) return new ErrorClass({
+		code: "UNKNOWN_ERROR",
+		status: response.status,
+		message: `HTTP ${response.status} ${response.statusText}`.trim(),
+		userMessage: "Something went wrong. Please try again.",
+		retryable: RETRYABLE_STATUSES.has(response.status),
+		details: { body: bodyText.slice(0, 500) }
+	});
+	const { error } = body;
+	const init = {
+		code: error.code,
+		status: response.status,
+		message: error.message,
+		userMessage: error.userMessage ?? error.message,
+		retryable: error.retryable ?? RETRYABLE_STATUSES.has(response.status),
+		retryAfterSeconds: error.retryAfterSeconds ?? null,
+		...error.provider !== void 0 && { provider: error.provider },
+		...error.details !== void 0 && { details: error.details }
+	};
+	if (response.status === 409 && error.code === "PROVIDER_CHANGED" && isProviderChangedBody(body)) return new ProviderChangedError({
+		...init,
+		newQuote: body.newQuote,
+		originalProvider: body.originalProvider,
+		newProvider: body.newProvider
+	});
+	return new ErrorClass(init);
+}
+//#endregion
+//#region src/core/sleep.ts
+/** Waits `ms`, but stops early (rejecting) if the caller's signal aborts. */
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) return reject(signal.reason);
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		function onAbort() {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
+//#region src/core/validation.ts
+/**
+* Checks a numeric option, with a message naming exactly what is wrong:
+* - `TypeError` if it isn't a number at all (e.g. the string `"5000"`).
+* - `RangeError` if it is a number but not a whole number (e.g. `1500.5`, `NaN`), or below `min`.
+*
+* Used for numeric options such as `timeoutMs` and `maxRetries`. Whole numbers only: `timeoutMs` is passed to
+* `AbortSignal.timeout`, which rejects fractions (e.g. `1500.5`) on every request with Node's own error about a
+* `"delay"` argument. Checking here reports a more valuable error to clients instead.
+*
+* @example
+* assertIntegerAtLeast("timeoutMs", options.timeoutMs, 1);
+*/
+function assertIntegerAtLeast(name, value, min) {
+	if (typeof value !== "number") throw new TypeError(`Pegaroute: \`${name}\` must be a number, received ${value === null ? "null" : typeof value}`);
+	if (!Number.isInteger(value)) throw new RangeError(`Pegaroute: \`${name}\` must be a whole number, received ${value}`);
+	if (value < min) throw new RangeError(`Pegaroute: \`${name}\` must be >= ${min}, received ${value}`);
+}
+//#endregion
+//#region src/core/http.ts
+/** If the server asks us to wait longer than this, give up instead of blocking the caller. */
+const MAX_RETRY_AFTER_SECONDS = 60;
+/** Exponential backoff bounds, used when the server doesn't send `Retry-After`. */
+const INITIAL_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 8e3;
+/** Sends requests to the Pegaroute API: auth, timeouts, retries and error mapping. */
+var HttpClient = class {
+	#config;
+	constructor(config) {
+		this.#config = config;
+	}
+	/** Sends a request, retrying GETs on connection errors and on errors marked `retryable` (see `errorFromResponse`). */
+	async request(request, options = {}) {
+		if (options.timeoutMs !== void 0) assertIntegerAtLeast("timeoutMs", options.timeoutMs, 1);
+		const maxRetries = request.method === "GET" ? this.#config.maxRetries : 0;
+		for (let attempt = 0;; attempt++) {
+			let response;
+			let bodyText;
+			try {
+				({response, bodyText} = await this.#send(request, options));
+			} catch (error) {
+				if (!(error instanceof ConnectionError) || attempt >= maxRetries) throw error;
+				await sleep(backoffMs(attempt), options.signal);
+				continue;
+			}
+			if (response.ok) return parseJson(response, bodyText);
+			if (request.successStatuses?.includes(response.status)) {
+				const body = tryParseJson(bodyText);
+				if (body !== void 0 && !isPegarouteErrorEnvelope(body)) return body;
+			}
+			const error = errorFromResponse(response, bodyText);
+			if (attempt >= maxRetries || !error.retryable) throw error;
+			const delayMs = retryDelayMs(response, error, attempt);
+			if (delayMs === null) throw error;
+			await sleep(delayMs, options.signal);
+		}
+	}
+	/** Performs one attempt, including reading the body, under the timeout. */
+	async #send(request, options) {
+		const timeoutMs = options.timeoutMs ?? this.#config.timeoutMs;
+		const timeoutSignal = AbortSignal.timeout(timeoutMs);
+		const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal;
+		const headers = {
+			Accept: "application/json",
+			"X-API-Key": this.#config.apiKey
+		};
+		if (request.body !== void 0) headers["Content-Type"] = "application/json";
+		let response;
+		try {
+			response = await this.#config.fetch(buildUrl(this.#config.baseUrl, request.path, request.query), {
+				method: request.method,
+				headers,
+				...request.body !== void 0 && { body: JSON.stringify(request.body) },
+				signal
+			});
+			return {
+				response,
+				bodyText: await response.text()
+			};
+		} catch (error) {
+			if (options.signal?.aborted) throw options.signal.reason;
+			const status = response?.status ?? null;
+			if (timeoutSignal.aborted) throw new TimeoutError({
+				code: "TIMEOUT",
+				status,
+				message: `Request timed out after ${timeoutMs}ms`,
+				userMessage: "The request took too long. Please try again.",
+				retryable: true,
+				cause: error
+			});
+			throw new ConnectionError({
+				code: "CONNECTION_ERROR",
+				status,
+				message: error instanceof Error ? error.message : "Connection failed",
+				userMessage: "Could not reach Pegaroute. Please try again.",
+				retryable: true,
+				cause: error
+			});
+		}
+	}
+};
+/** Joins base URL and path, and appends the defined query params. */
+function buildUrl(baseUrl, path, query) {
+	const url = new URL(baseUrl + path);
+	for (const [key, value] of Object.entries(query ?? {})) if (value !== void 0) url.searchParams.set(key, String(value));
+	return url.toString();
+}
+/** Parses a successful response body; a non-JSON body (e.g. a proxy page) becomes `INVALID_RESPONSE`. */
+function parseJson(response, bodyText) {
+	try {
+		return JSON.parse(bodyText);
+	} catch (cause) {
+		throw new PegarouteError({
+			code: "INVALID_RESPONSE",
+			status: response.status,
+			message: `Expected a JSON response but received: ${bodyText.slice(0, 100)}`,
+			userMessage: "Something went wrong. Please try again.",
+			retryable: false,
+			details: { body: bodyText.slice(0, 500) },
+			cause
+		});
+	}
+}
+/** Parses JSON, returning `undefined` instead of throwing when the text isn't valid JSON. */
+function tryParseJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+/** Retry-After (header, then body) wins; `null` means the wait is too long to retry. */
+function retryDelayMs(response, error, attempt) {
+	const retryAfterSeconds = parseRetryAfter(response.headers.get("retry-after")) ?? error.retryAfterSeconds;
+	if (retryAfterSeconds === null) return backoffMs(attempt);
+	if (retryAfterSeconds > MAX_RETRY_AFTER_SECONDS) return null;
+	return retryAfterSeconds * 1e3;
+}
+/** Parses `Retry-After` as delta-seconds or an HTTP date. */
+function parseRetryAfter(header) {
+	if (header === null) return null;
+	const seconds = Number(header);
+	if (Number.isFinite(seconds)) return Math.max(0, seconds);
+	const date = Date.parse(header);
+	return Number.isNaN(date) ? null : Math.max(0, (date - Date.now()) / 1e3);
+}
+/** Exponential backoff (0.5s, 1s, 2s … capped at 8s) with ±25% jitter so clients don't retry in lockstep. */
+function backoffMs(attempt) {
+	return Math.min(INITIAL_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS) * (.75 + Math.random() * .5);
+}
+//#endregion
+//#region src/resources/chains.ts
+/** Chains Pegaroute supports. Available as `pr.chains`. */
+var Chains = class {
+	#http;
+	constructor(http) {
+		this.#http = http;
+	}
+	/**
+	* Lists every supported chain.
+	*
+	* @example
+	* const { chains } = await pr.chains.list();
+	*/
+	list(options) {
+		return this.#http.request({
+			method: "GET",
+			path: "/chains"
+		}, options);
+	}
+};
+//#endregion
+//#region src/resources/providers.ts
+/** Swap providers behind Pegaroute and their live status. Available as `pr.providers`. */
+var Providers = class {
+	#http;
+	constructor(http) {
+		this.#http = http;
+	}
+	/**
+	* Lists the providers that are switched on, or every provider with `includeDisabled: true`.
+	*
+	* @example
+	* const { providers } = await pr.providers.list({ includeDisabled: true });
+	*/
+	list(params = {}, options) {
+		return this.#http.request({
+			method: "GET",
+			path: "/providers",
+			query: { includeDisabled: params.includeDisabled }
+		}, options);
+	}
+};
+//#endregion
+//#region src/resources/quotes.ts
+/** Swap quotes. Available as `pr.quotes`. */
+var Quotes = class {
+	#http;
+	constructor(http) {
+		this.#http = http;
+	}
+	/**
+	* Gets routes for a swap from every available provider.
+	*
+	* Throws `BadRequestError` for invalid input or an amount too low for every provider (`AMOUNT_TOO_LOW`),
+	* and `ServiceUnavailableError` when the chain is disabled (`CHAIN_DISABLED`).
+	*
+	* @example
+	* const quote = await pr.quotes.get({ fromChain: "ETH", fromToken: "ETH", toChain: "BTC", toToken: "BTC", amount: "0.5" });
+	* const best = quote.routes[0];
+	*/
+	get(params, options) {
+		const query = {
+			fromChain: params.fromChain,
+			fromToken: params.fromToken,
+			toChain: params.toChain,
+			toToken: params.toToken,
+			amount: params.amount,
+			private: params.private,
+			destinationAddress: params.destinationAddress,
+			senderAddress: params.senderAddress,
+			refundAddress: params.refundAddress
+		};
+		return this.#http.request({
+			method: "GET",
+			path: "/quote",
+			query
+		}, options);
+	}
+};
+//#endregion
+//#region src/core/polling.ts
+/**
+* Fetches a value at a fixed interval until `isDone` returns `true`, then returns that value.
+*
+* Stops early when:
+* - the deadline passes → throws `timeoutError(lastValue)`
+* - the caller's signal aborts → rethrows its reason, like every other SDK call
+* - a fetch fails → rethrows that error unchanged
+*
+* @example
+* const swap = await pollUntil({
+*   fetch: (signal) => swaps.get(id, { signal }),
+*   isDone: (swap) => isTerminalStatus(swap.status),
+*   intervalMs: 10_000,
+*   timeoutMs: 3_600_000,
+*   timeoutError: (lastSwap) => new WaitTimeoutError({ … }),
+* });
+*/
+async function pollUntil(config) {
+	const deadline = AbortSignal.timeout(config.timeoutMs);
+	const signal = config.signal ? AbortSignal.any([config.signal, deadline]) : deadline;
+	let lastValue = null;
+	try {
+		for (;;) {
+			lastValue = await config.fetch(signal);
+			if (config.isDone(lastValue)) return lastValue;
+			await sleep(config.intervalMs, signal);
+		}
+	} catch (error) {
+		if (config.signal?.aborted) throw config.signal.reason;
+		if (deadline.aborted) throw config.timeoutError(lastValue);
+		throw error;
+	}
+}
+//#endregion
+//#region src/resources/swaps.ts
+/** Default wait between polls: Pegaroute refreshes a swap every 15 s, and rate limits at 10 requests/s. */
+const DEFAULT_POLL_INTERVAL_MS = 1e4;
+/** Minimum polling interval: Polling faster than this only spends the rate limit: Pegaroute won't have anything new due to caching. */
+const MIN_POLL_INTERVAL_MS = 1e3;
+/** Default deadline for the whole wait: long enough for slow streaming swaps. */
+const DEFAULT_WAIT_TIMEOUT_MS = 36e5;
+/** Swap creation and tracking. Available as `pr.swaps`. */
+var Swaps = class {
+	#http;
+	constructor(http) {
+		this.#http = http;
+	}
+	/**
+	* Creates a swap and returns what the user must sign.
+	*
+	* Never retried: the HTTP client only retries GET requests, so a timeout can't create a duplicate swap.
+	*
+	* Throws `ProviderChangedError` when the quoted route is gone: retry with its `newQuote`.
+	* Throws `QuoteExpiredError` when the quote expired, and `BadRequestError` for invalid input or
+	* parameters that don't match the quote (`QUOTE_MISMATCH`).
+	*
+	* @example
+	* const swap = await pr.swaps.create({
+	*   fromChain: "ETH", fromToken: "ETH", toChain: "BTC", toToken: "BTC", amount: "0.5",
+	*   senderAddress: "0xabc…", destinationAddress: "bc1q…",
+	*   quoteId: quote.quoteId, routeProvider: quote.routes[0].provider,
+	* });
+	* // send swap.execution to the frontend for signing
+	*/
+	create(params, options) {
+		const query = { private: params.private };
+		const body = {
+			fromChain: params.fromChain,
+			fromToken: params.fromToken,
+			toChain: params.toChain,
+			toToken: params.toToken,
+			amount: params.amount,
+			destinationAddress: params.destinationAddress,
+			senderAddress: params.senderAddress,
+			refundAddress: params.refundAddress,
+			slippageTolerance: params.slippageTolerance,
+			streaming: params.streaming,
+			quoteId: params.quoteId,
+			routeProvider: params.routeProvider
+		};
+		return this.#http.request({
+			method: "POST",
+			path: "/swap",
+			query,
+			body
+		}, options);
+	}
+	/**
+	* Gets a swap's current state. Throws `NotFoundError` for an unknown ID.
+	*
+	* @example
+	* const swap = await pr.swaps.get(transactionId);
+	* if (swap.status === "fail") console.log(swap.error?.userMessage, swap.refund);
+	*/
+	get(transactionId, options) {
+		return this.#http.request({
+			method: "GET",
+			path: `/swap/${encodeURIComponent(transactionId)}`
+		}, options);
+	}
+	/**
+	* Polls `swaps.get` until the swap reaches a terminal status (`success` or `fail`), then returns it.
+	* Webhooks are the better fit for production; use this as a fallback or in scripts.
+	*
+	* Throws `WaitTimeoutError` (with the last swap seen) if `timeoutMs` passes first. A failing poll is thrown
+	* unchanged, after `swaps.get`'s own retries.
+	*
+	* @example
+	* const final = await pr.swaps.waitForCompletion(swap.transactionId);
+	* if (final.status === "fail") console.log(final.error?.userMessage, final.refund);
+	*/
+	async waitForCompletion(transactionId, options = {}) {
+		const { intervalMs = DEFAULT_POLL_INTERVAL_MS, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS, signal } = options;
+		assertIntegerAtLeast("intervalMs", intervalMs, MIN_POLL_INTERVAL_MS);
+		assertIntegerAtLeast("timeoutMs", timeoutMs, 1);
+		return pollUntil({
+			fetch: (pollSignal) => this.get(transactionId, { signal: pollSignal }),
+			isDone: (swap) => isTerminalStatus(swap.status),
+			intervalMs,
+			timeoutMs,
+			signal,
+			timeoutError: (lastSwap) => new WaitTimeoutError({
+				code: "WAIT_TIMEOUT",
+				status: null,
+				message: `Swap ${transactionId} did not reach a terminal status within ${timeoutMs}ms`,
+				userMessage: "The swap is taking longer than expected. Check its status again later.",
+				retryable: false,
+				lastSwap
+			})
+		});
+	}
+	/**
+	* Gets a swap's audit log: every internal status change, oldest first.
+	*
+	* @example
+	* const { events } = await pr.swaps.events(transactionId);
+	*/
+	events(transactionId, options) {
+		return this.#http.request({
+			method: "GET",
+			path: `/swap/${encodeURIComponent(transactionId)}/events`
+		}, options);
+	}
+	/**
+	* Reports the hash of the source transaction the user broadcast, so Pegaroute starts tracking it.
+	* Returns the internal status `"submitted"`.
+	*
+	* @example
+	* await pr.swaps.submitTxHash(swap.transactionId, { txHash });
+	*/
+	submitTxHash(transactionId, params, options) {
+		const body = {
+			txHash: params.txHash,
+			signature: params.signature
+		};
+		return this.#http.request({
+			method: "POST",
+			path: `/swap/${encodeURIComponent(transactionId)}/txhash`,
+			body
+		}, options);
+	}
+};
+//#endregion
+//#region src/resources/tokens.ts
+/** Tokens Pegaroute recognises on each chain. Available as `pr.tokens`. */
+var Tokens = class {
+	#http;
+	constructor(http) {
+		this.#http = http;
+	}
+	/**
+	* Lists the tokens on one chain. Throws `BadRequestError` (`VALIDATION_ERROR`) for an unknown chain.
+	*
+	* @param chain A chain ID from `chains.list()`; case is ignored.
+	*
+	* @example
+	* const { tokens } = await pr.tokens.list("SOL");
+	*/
+	list(chain, options) {
+		return this.#http.request({
+			method: "GET",
+			path: "/tokens",
+			query: { chain }
+		}, options);
+	}
+};
+//#endregion
+//#region src/core/pagination.ts
+/**
+* The result of a cursor-paginated list: await it for one page, or iterate it for every item.
+*
+* Nothing is requested until it is awaited or iterated. Awaiting and then iterating the same
+* `PagePromise` fetches the first page only once.
+*
+* `.catch()` and `.finally()` only cover the first page. When iterating, later pages are fetched inside
+* the loop, so wrap the loop in `try`/`catch` to handle a failure on any page.
+*
+* @example
+* // One page, as the API returns it
+* const page = await pr.transactions.list({ count: 50 });
+*
+* // Every item, fetching the next page as needed
+* try {
+*   for await (const tx of pr.transactions.list()) console.log(tx.id);
+* } catch (e) {
+*   // any page failed
+* }
+*/
+var PagePromise = class {
+	/** Shown by `Object.prototype.toString`, like `[object Promise]` for a real promise. */
+	[Symbol.toStringTag] = "PagePromise";
+	#config;
+	/** The first page's request, started on first use and then shared. */
+	#firstPage;
+	constructor(config) {
+		this.#config = config;
+	}
+	/** Resolves to the first page, so `await` works. */
+	then(onfulfilled, onrejected) {
+		return this.#getFirstPage().then(onfulfilled, onrejected);
+	}
+	/** Handles a failure to fetch the first page, like `Promise.prototype.catch`. */
+	catch(onrejected) {
+		return this.#getFirstPage().catch(onrejected);
+	}
+	/** Runs once the first page is fetched or has failed, like `Promise.prototype.finally`. */
+	finally(onfinally) {
+		return this.#getFirstPage().finally(onfinally);
+	}
+	/** Yields every item of every page, fetching each page when the previous one is used up. */
+	async *[Symbol.asyncIterator]() {
+		let page = await this.#getFirstPage();
+		while (true) {
+			yield* this.#config.items(page);
+			const cursor = this.#config.nextCursor(page);
+			if (cursor === null) return;
+			page = await this.#config.fetchPage(cursor);
+		}
+	}
+	/** Fetches the first page once, however many times it is awaited or iterated. */
+	#getFirstPage() {
+		this.#firstPage ??= this.#config.fetchPage(this.#config.firstCursor);
+		return this.#firstPage;
+	}
+};
+//#endregion
+//#region src/resources/transactions.ts
+/** Swap history for your integration. Available as `pr.transactions`. */
+var Transactions = class {
+	#http;
+	constructor(http) {
+		this.#http = http;
+	}
+	/**
+	* Lists your swaps, newest first. Await it for one page, or iterate it with `for await` to walk every page.
+	*
+	* @example
+	* // One page
+	* const { transactions, pagination } = await pr.transactions.list({ count: 50 });
+	*
+	* // Every failed swap, across pages
+	* for await (const tx of pr.transactions.list({ status: "failed" })) {
+	*   console.log(tx.id, tx.error?.userMessage);
+	* }
+	*/
+	list(params = {}, options) {
+		return new PagePromise({
+			fetchPage: (cursor) => this.#http.request({
+				method: "GET",
+				path: "/transactions",
+				query: {
+					status: params.status,
+					provider: params.provider,
+					startTime: params.startTime,
+					endTime: params.endTime,
+					count: params.count,
+					cursor
+				}
+			}, options),
+			firstCursor: params.cursor,
+			items: (page) => page.transactions,
+			nextCursor: (page) => page.pagination.hasMore ? page.pagination.nextCursor : null
+		});
+	}
+};
+//#endregion
+//#region src/client.ts
+const DEFAULT_TIMEOUT_MS = 3e4;
+const DEFAULT_MAX_RETRIES = 2;
+let browserWarningShown = false;
+/** Pegaroute API client. Server-side only: it holds your API key. */
+var Pegaroute = class {
+	/** The HTTP client that all resource namespaces (`quotes`, `swaps`, …) send their requests through. Internal only. */
+	#http;
+	/** Supported chains. */
+	chains;
+	/** Supported tokens per chain. */
+	tokens;
+	/** Swap providers and their status. */
+	providers;
+	/** Swap quotes. */
+	quotes;
+	/** Swap creation and tracking. */
+	swaps;
+	/** Swap history for your integration. */
+	transactions;
+	constructor(options) {
+		const { apiKey, baseUrl, timeoutMs = DEFAULT_TIMEOUT_MS, maxRetries = DEFAULT_MAX_RETRIES } = options;
+		if (typeof apiKey !== "string" || apiKey.trim() === "") throw new TypeError("Pegaroute: `apiKey` is required");
+		if (!/^[\x21-\x7E]+$/.test(apiKey)) throw new TypeError("Pegaroute: `apiKey` contains whitespace or characters not allowed in an HTTP header");
+		if (typeof baseUrl !== "string" || !URL.canParse(baseUrl)) throw new TypeError("Pegaroute: `baseUrl` must be an absolute URL");
+		assertIntegerAtLeast("timeoutMs", timeoutMs, 1);
+		assertIntegerAtLeast("maxRetries", maxRetries, 0);
+		const fetchImpl = options.fetch ?? globalThis.fetch;
+		if (typeof fetchImpl !== "function") throw new TypeError("Pegaroute: no `fetch` available; pass `options.fetch`");
+		warnIfBrowser();
+		this.#http = new HttpClient({
+			apiKey,
+			baseUrl: baseUrl.replace(/\/+$/, ""),
+			timeoutMs,
+			maxRetries,
+			fetch: (url, init) => fetchImpl(url, init)
+		});
+		this.chains = new Chains(this.#http);
+		this.tokens = new Tokens(this.#http);
+		this.providers = new Providers(this.#http);
+		this.quotes = new Quotes(this.#http);
+		this.swaps = new Swaps(this.#http);
+		this.transactions = new Transactions(this.#http);
+	}
+	/**
+	* Returns Pegaroute's health: database, write-ahead log and every provider.
+	*
+	* Unlike other methods, this does not throw when Pegaroute answers 503 because its database is down:
+	* it returns the body with `status: "degraded"` instead. Other failures (401, timeouts, …) still throw.
+	*
+	* @example
+	* const health = await pr.health();
+	* if (health.status === "degraded") alert(health);
+	*/
+	health(options) {
+		return this.#http.request({
+			method: "GET",
+			path: "/health",
+			successStatuses: [503]
+		}, options);
+	}
+	/**
+	* Checks that Pegaroute is reachable.
+	*
+	* @example
+	* await pr.ping(); // { response: "pong", timestamp: "…", service: "pegaroute" }
+	*/
+	ping(options) {
+		return this.#http.request({
+			method: "GET",
+			path: "/ping"
+		}, options);
+	}
+};
+function warnIfBrowser() {
+	const g = globalThis;
+	if (browserWarningShown || g.window === void 0 || g.document === void 0) return;
+	browserWarningShown = true;
+	console.warn("[pegaroute] The Pegaroute client appears to be running in a browser. It sends your API key with every request, so please use it from your backend only.");
+}
+//#endregion
+//#region src/webhooks.ts
+/**
+* A webhook delivery failed verification: don't trust its body. Answer with a 4xx (e.g. 401).
+*
+* Not a `PegarouteError`: no API request was made, so its HTTP fields wouldn't mean anything.
+*/
+var WebhookVerificationError = class extends Error {
+	/**
+	* What was wrong:
+	* - `missing_signature`: no `X-Pegasus-Signature` header.
+	* - `invalid_signature`: the signature doesn't match the body and secret (wrong secret, altered body, or the
+	*   body was re-serialised instead of passed raw).
+	* - `invalid_payload`: the signature matched, but the body isn't a JSON object.
+	*/
+	reason;
+	constructor(reason, message, options) {
+		super(message, options);
+		this.name = "WebhookVerificationError";
+		this.reason = reason;
+	}
+};
+/** Optional prefix some senders put before the hex digest. Pegaroute sends bare hex today; both are accepted. */
+const SIGNATURE_PREFIX = "sha256=";
+/** An HMAC-SHA256 digest in hex: 32 bytes = 64 characters. */
+const HEX_DIGEST = /^[0-9a-f]{64}$/i;
+/**
+* Checks that a webhook came from Pegaroute and returns its typed event.
+*
+* The signature is an HMAC-SHA256 of the raw body, keyed with your webhook secret. Delivery is at-least-once, so
+* the same event can arrive more than once: make handlers idempotent.
+*
+* The signature proves who sent the body, not when: it has no timestamp, and events carry no ID to deduplicate on,
+* so anyone who obtains a delivery can send it again later and it still verifies. Treat an event as a hint and
+* confirm with `swaps.get` before acting on funds.
+*
+* Throws `WebhookVerificationError` when the delivery can't be trusted, and `TypeError` for a coding mistake
+* (`secret` missing, or `signature` neither a string nor an array).
+*
+* @example
+* app.post("/webhooks/pegaroute", express.raw({ type: "application/json" }), async (req, res) => {
+*   try {
+*     const event = await verifyWebhook({
+*       rawBody: req.body,
+*       signature: req.headers["x-pegasus-signature"],
+*       secret: process.env.PEGAROUTE_WEBHOOK_SECRET!,
+*     });
+*     if (event.event === "transaction.completed") {
+*       // The event may be a replay: confirm the current state before acting on funds.
+*       const swap = await pr.swaps.get(event.data.transactionId);
+*       if (swap.status === "success") await markPaid(swap.transactionId); // idempotent
+*     }
+*     res.sendStatus(200);
+*   } catch (e) {
+*     if (e instanceof WebhookVerificationError) return res.sendStatus(401);
+*     throw e;
+*   }
+* });
+*/
+async function verifyWebhook(params) {
+	const { rawBody, signature, secret } = params;
+	if (typeof secret !== "string" || secret.trim() === "") throw new TypeError("Pegaroute: `secret` is required to verify webhooks");
+	if (signature === void 0 || signature === null || signature === "") throw new WebhookVerificationError("missing_signature", "Missing X-Pegasus-Signature header");
+	if (Array.isArray(signature)) throw new WebhookVerificationError("invalid_signature", "Received more than one X-Pegasus-Signature header");
+	if (typeof signature !== "string") throw new TypeError(`Pegaroute: \`signature\` must be a string, received ${typeof signature}`);
+	const digest = signature.startsWith(SIGNATURE_PREFIX) ? signature.slice(7) : signature;
+	if (!HEX_DIGEST.test(digest)) throw new WebhookVerificationError("invalid_signature", "X-Pegasus-Signature is not an HMAC-SHA256 hex digest");
+	const bodyBytes = typeof rawBody === "string" ? new TextEncoder().encode(rawBody) : new Uint8Array(rawBody);
+	const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["verify"]);
+	if (!await crypto.subtle.verify("HMAC", key, hexToBytes(digest), bodyBytes)) throw new WebhookVerificationError("invalid_signature", "X-Pegasus-Signature does not match the body. Check that `secret` is the integration's current webhook secret, and that `rawBody` is the body exactly as received (not parsed and re-serialised).");
+	const bodyText = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody);
+	let body;
+	try {
+		body = JSON.parse(bodyText);
+	} catch (cause) {
+		throw new WebhookVerificationError("invalid_payload", "Webhook body is not valid JSON", { cause });
+	}
+	if (typeof body !== "object" || body === null || Array.isArray(body)) throw new WebhookVerificationError("invalid_payload", "Webhook body is not a JSON object");
+	return body;
+}
+/** Converts a hex string (already checked to be valid, even-length hex) to bytes. */
+function hexToBytes(hex) {
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < bytes.length; i++) bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+	return bytes;
+}
+//#endregion
+export { AuthenticationError, BadRequestError, ConflictError, ConnectionError, InternalServerError, NotFoundError, Pegaroute, PegarouteError, PermissionDeniedError, ProviderChangedError, QuoteExpiredError, RateLimitError, ServiceUnavailableError, TimeoutError, UnprocessableEntityError, WaitTimeoutError, WebhookVerificationError, hasQuoteRouteFees, isExecutionFamily, isExecutionMode, isTerminalStatus, toExternalStatus, verifyWebhook };