UNPKG

@lifi/composer-sdk

Version:

Public Composer SDK for building and submitting flows

225 lines • 8.7 kB
import { ComposeErrorKind, ComposeRouteErrorKind, DeliveryErrorDetails, FailedPreparedOp, Shortfall, SimulationRevert } 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. * - `PAYMENT_REQUIRED` — HTTP 402: the integration's prepaid credit balance cannot cover the call; top up with POST /credits/topup. * - `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" | "PAYMENT_REQUIRED" | "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;