@lifi/composer-sdk
Version:
Public Composer SDK for building and submitting flows
227 lines • 8.62 kB
text/typescript
import { ComposeErrorKind, ComposeRouteErrorKind, DeliveryErrorDetails, FailedPreparedOp, Shortfall, SimulationRevert } from "@lifi/compose-spec";
//#region src/errors.d.ts
/**
* Machine-readable error codes returned by the SDK.
*
* - `NETWORK_ERROR` — The HTTP request failed (DNS, timeout, connection refused).
* - `VALIDATION_ERROR` — The server rejected the request (HTTP 400/422).
* - `UNAUTHENTICATED` — The request lacks valid authentication credentials (HTTP 401).
* - `FORBIDDEN` — The server understood the request but refuses to authorise it (HTTP 403).
* - `SERVER_ERROR` — The server returned a 5xx status.
* - `RATE_LIMITED` — The server returned HTTP 429.
* - `NOT_FOUND` — The requested resource does not exist (HTTP 404).
* - `UNKNOWN_ERROR` — An unexpected error that doesn't fit other categories.
*/
export type ComposeErrorCode = "NETWORK_ERROR" | "VALIDATION_ERROR" | "UNAUTHENTICATED" | "FORBIDDEN" | "SERVER_ERROR" | "RATE_LIMITED" | "NOT_FOUND" | "UNKNOWN_ERROR";
/** Version details returned when the backend rejects an outdated SDK. */
export interface ComposeSdkOutdated {
readonly sdkVersion: string;
readonly serverVersion: string;
readonly minimumSdkVersion: string;
}
/**
* Version details attached when the SDK is ahead of the backend it reached.
* Raised by the backend's version gate, or by the SDK itself when the
* `x-lifi-composer-version` response header names an older contract than the
* one this SDK was built against.
*/
export interface ComposeServerOutdated {
readonly sdkVersion: string;
readonly serverVersion: string;
}
/**
* Error class for all failures originating from the Compose SDK or API.
*
* Includes structured metadata beyond the error message to support
* programmatic error handling.
*
* @example
* ```ts
* try {
* await builder.compile(run);
* } catch (e) {
* if (isComposeError(e) && e.code === 'VALIDATION_ERROR') {
* console.error('Invalid request:', e.message, e.path);
* }
* }
* ```
*/
export declare class ComposeError extends Error {
override readonly name = "ComposeError";
/** Machine-readable error category. */
readonly code: ComposeErrorCode;
/** HTTP status code, when the error originated from an HTTP response. */
readonly status?: number;
/** The request URL that produced the error. */
readonly url?: string;
/** Server-provided error kind for finer-grained classification. */
readonly kind?: ComposeErrorKind | ComposeRouteErrorKind;
/**
* Where a validation error points: the node id for a rejection of an
* authored node, or a JSON-pointer path for a rejection of the request shape.
*/
readonly path?: string;
/**
* The input port of {@link ComposeError.path}'s node whose binding caused the
* error. Set when the rejection is about what a port binds rather than about
* the node's config.
*/
readonly port?: string;
/**
* The one edit that clears the error, written for whoever authored the flow.
* Set on `continuation.settle` authoring rejections; may be absent on other
* `validation_error`s.
*/
readonly fix?: string;
/**
* The amount the flow was short by, when the error's cause is an amount that
* cannot cover what a step needs: `required` is the least amount that would
* clear the step, `available` the amount the flow had, both decimal strings
* in the token's units. A failed op carries its own in `failedOps[].shortfall`.
*/
readonly shortfall?: Shortfall;
/**
* Simulation revert diagnostics attached to `simulation_revert` errors.
* Contains the raw error bytes and decoded error candidates when the
* backend can parse the revert reason.
*/
readonly details?: SimulationRevert;
/**
* The delivery tranche's reason, first quote, and abandoned escrow,
* attached to `delivery_error` errors. Narrow with
* {@link isComposeDeliveryError}.
*/
readonly delivery?: DeliveryErrorDetails;
/**
* The prepared ops that failed, attached to `preparation_error` errors.
* Each entry carries the `callId` of the failing node so callers can drop
* the unroutable legs and resubmit a smaller flow.
*/
readonly failedOps?: readonly FailedPreparedOp[];
/**
* The `callId`s of the prepared ops that succeeded, attached to
* `preparation_error` errors alongside {@link ComposeError.failedOps}.
*/
readonly succeededOps?: readonly string[];
/** Version details attached only to `sdk_outdated` errors. */
readonly sdkOutdated?: ComposeSdkOutdated;
/** Version details attached only to `server_outdated` errors. */
readonly serverOutdated?: ComposeServerOutdated;
constructor(code: ComposeErrorCode, message: string, options?: {
status?: number;
url?: string;
cause?: unknown;
kind?: ComposeErrorKind | ComposeRouteErrorKind;
path?: string;
port?: string;
fix?: string;
shortfall?: Shortfall;
details?: SimulationRevert;
delivery?: DeliveryErrorDetails;
failedOps?: readonly FailedPreparedOp[];
succeededOps?: readonly string[];
sdkOutdated?: ComposeSdkOutdated;
serverOutdated?: ComposeServerOutdated;
});
}
/**
* The per-op preparation diagnostics carried by `preparation_error` responses,
* with both arrays known to be present. Produced by narrowing with
* {@link isComposePreparationError}.
*/
export interface ComposePreparationOps {
readonly failedOps: readonly FailedPreparedOp[];
readonly succeededOps: readonly string[];
}
/**
* Type guard that narrows an unknown error to {@link ComposeError}.
* @param e - The value to check.
* @returns `true` if `e` is an instance of `ComposeError`.
*/
export declare const isComposeError: (e: unknown) => e is ComposeError;
/**
* Type guard for `preparation_error` failures (HTTP 422): a mixed basket where
* some prepared ops failed and others succeeded. Narrows both
* {@link ComposeError.failedOps} and {@link ComposeError.succeededOps} to
* present, so callers can read them without a cast or a truthiness check.
*
* @param e - The value to check.
* @returns `true` if `e` is a `ComposeError` carrying per-op preparation diagnostics.
*
* @example
* ```ts
* try {
* await builder.compile(run);
* } catch (e) {
* if (isComposePreparationError(e)) {
* console.error('Failed ops:', e.failedOps);
* console.error('Succeeded ops:', e.succeededOps);
* }
* }
* ```
*/
export declare const isComposePreparationError: (e: unknown) => e is ComposeError & ComposePreparationOps;
/**
* Type guard for `delivery_error` failures (HTTP 422): a bridge delivering into
* a settle escrow no longer fits it. Narrows {@link ComposeError.delivery} to
* present. Recompile: each compile quotes and registers afresh.
*
* @param e - The value to check.
* @returns `true` if `e` is a `ComposeError` carrying delivery details.
*/
export declare const isComposeDeliveryError: (e: unknown) => e is ComposeError & {
readonly delivery: DeliveryErrorDetails;
};
/**
* Narrows an outdated-SDK rejection to its required version details.
*
* @example
* ```ts
* try {
* await builder.compile(run);
* } catch (e) {
* if (isComposeSdkOutdatedError(e)) {
* console.error(`Upgrade to at least ${e.sdkOutdated.minimumSdkVersion}`);
* return;
* }
* throw e;
* }
* ```
*/
export declare const isComposeSdkOutdatedError: (e: unknown) => e is ComposeError & {
readonly sdkOutdated: ComposeSdkOutdated;
};
/**
* Narrows a server-behind-SDK rejection to its required version details.
*
* This is the deploy-window error: the SDK on npm is ahead of the backend that
* answered. Pin the SDK to the server's `major.minor`, or wait for the rollout.
*
* @example
* ```ts
* try {
* await builder.compile(run);
* } catch (e) {
* if (isComposeServerOutdatedError(e)) {
* console.error(`Server serves ${e.serverOutdated.serverVersion}`);
* return;
* }
* throw e;
* }
* ```
*/
export declare const isComposeServerOutdatedError: (e: unknown) => e is ComposeError & {
readonly serverOutdated: ComposeServerOutdated;
};
/**
* Constructs a {@link ComposeError} from an HTTP error response, extracting
* structured error details from the response body when available.
*
* @param status - The HTTP status code.
* @param body - The raw response body text.
* @param url - The request URL that produced the error.
* @returns A `ComposeError` with the appropriate error code and metadata.
*/
export declare const errorFromHttpResponse: (status: number, body: string, url: string) => ComposeError;
//#endregion
//# sourceMappingURL=errors.d.cts.map