@lifi/composer-sdk/dist/errors.d.ts

Public Composer SDK for building and submitting flows

import { ComposeErrorKind, ComposeRouteErrorKind, SimulationRevert, FailedPreparedOp } from '@lifi/compose-spec';

/**
 * 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.
 */
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. */
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.
 */
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);
 *   }
 * }
 * ```
 */
declare class ComposeError extends Error {
    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;
    /** JSON-pointer path to the field that caused a validation error. */
    readonly path?: string;
    /**
     * 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 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;
        details?: SimulationRevert;
        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}.
 */
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`.
 */
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);
 *   }
 * }
 * ```
 */
declare const isComposePreparationError: (e: unknown) => e is ComposeError & ComposePreparationOps;
/**
 * 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;
 * }
 * ```
 */
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;
 * }
 * ```
 */
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.
 */
declare const errorFromHttpResponse: (status: number, body: string, url: string) => ComposeError;

export { ComposeError, type ComposeErrorCode, type ComposePreparationOps, type ComposeSdkOutdated, type ComposeServerOutdated, errorFromHttpResponse, isComposeError, isComposePreparationError, isComposeSdkOutdatedError, isComposeServerOutdatedError };