@prismatic-io/spectral/dist/clients/http/index.d.ts

Utility library for building Prismatic connectors and code-native integrations

import type { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
import { type IAxiosRetryConfig } from "axios-retry";
import type { ActionInputParameters } from "../../types/ActionInputParameters";
import { inputs } from "./inputs";
export type HttpClient = AxiosInstance;
interface RetryConfig extends Omit<IAxiosRetryConfig, "retryDelay"> {
    /** The number of milliseconds to wait between retry attempts. */
    retryDelay?: IAxiosRetryConfig["retryDelay"] | number;
    /**
     * When true, all errors will be retried. When false, specify
     * a retryCondition function to determine when retries should occur.
     */
    retryAllErrors?: boolean;
    /**
     * When true, double the retryDelay after each attempt (e.g. 1000ms, 2000ms, 4000ms, 8000ms, etc.).
     * If no retryDelay is specified, defaults to axios-retry's exponentialDelay function.
     */
    useExponentialBackoff?: boolean;
}
export interface ClientProps {
    /** The API's base URL (e.g. `https://api.acme.com/v2/`). */
    baseUrl?: string;
    /** The type of response to expect. Set to 'json' to automatically parse a JSON response, or 'arraybuffer' for a binary file. */
    responseType?: AxiosRequestConfig["responseType"];
    /** Headers to send for all requests (e.g. Authorization header, etc.). */
    headers?: AxiosRequestConfig["headers"];
    /** URL Search parameters to add to all requests. */
    params?: Record<string, any>;
    /** The maximum amount of time (in milliseconds) to wait for a response. Defaults to infinity. */
    timeout?: number;
    /** When enabled, log all HTTP requests and responses. */
    debug?: boolean;
    /** Configuration used to determine if and how failed HTTP requests should be retried. */
    retryConfig?: RetryConfig;
}
export declare const toAxiosRetryConfig: ({ retryDelay, retryAllErrors, retryCondition, useExponentialBackoff, ...rest }: RetryConfig) => IAxiosRetryConfig;
/**
 * Creates a reusable Axios HTTP client pre-configured with a base URL,
 * headers, timeout, and optional retry logic. This is the recommended
 * way to make HTTP requests from custom component actions.
 *
 * @param props Configuration for the HTTP client.
 * @returns An Axios instance configured with the provided options.
 * @see {@link https://prismatic.io/docs/custom-connectors/connections/#using-the-built-in-createclient-http-client | Using the Built-in HTTP Client}
 * @example
 * import { createClient } from "@prismatic-io/spectral/dist/clients/http";
 *
 * const client = createClient({
 *   baseUrl: "https://api.acme.com/v2",
 *   headers: { Authorization: `Bearer ${accessToken}` },
 *   responseType: "json",
 *   timeout: 30000,
 *   debug: false,
 *   retryConfig: {
 *     retries: 3,
 *     retryDelay: 1000,
 *     useExponentialBackoff: true,
 *     retryAllErrors: false,
 *   },
 * });
 *
 * const { data } = await client.get("/items");
 */
export declare const createClient: ({ baseUrl, responseType, headers, timeout, params, debug, retryConfig, }: ClientProps) => HttpClient;
/**
 * A global error handler that examines a thrown error and yields additional
 * information if the error was produced by Spectral's HTTP client. If the
 * error is an Axios error, returns a structured object with the response
 * `data`, `status`, and `headers`. Otherwise, returns the error as-is.
 *
 * Commonly used as a component-level `hooks.error` handler.
 *
 * @param error A JavaScript error to handle.
 * @returns An error with data, status and headers if it was an Axios error, or the error otherwise.
 * @see {@link https://prismatic.io/docs/custom-connectors/error-handling/ | Error Handling}
 * @example
 * import { component } from "@prismatic-io/spectral";
 * import { handleErrors } from "@prismatic-io/spectral/dist/clients/http";
 *
 * export default component({
 *   key: "acme",
 *   display: { label: "Acme", description: "Acme connector", iconPath: "icon.png" },
 *   hooks: { error: handleErrors },
 *   actions: { ... },
 * });
 */
export declare const handleErrors: (error: unknown) => unknown;
type SendRawRequestValues = ActionInputParameters<typeof inputs>;
/**
 * This function sends a raw HTTP request with full control over method, URL,
 * headers, query parameters, and body. Used internally by `buildRawRequestAction`.
 *
 * @param baseUrl The base URL of the API you're integrating with.
 * @param values An object comprising the HTTP request you'd like to make.
 * @param authorizationHeaders Auth headers to apply to the request.
 * @returns The Axios response to the request.
 * @see {@link https://prismatic.io/docs/integrations/low-code-integration-designer/raw-request-actions/#building-an-http-raw-request-action-in-your-custom-component | Raw Request Actions}
 * @example
 * import { sendRawRequest } from "@prismatic-io/spectral/dist/clients/http";
 *
 * const response = await sendRawRequest(
 *   "https://api.acme.com/v2",
 *   {
 *     method: "GET",
 *     url: "/items",
 *     headers: [],
 *     queryParams: [{ key: "limit", value: "10" }],
 *     responseType: "json",
 *   },
 *   { Authorization: "Bearer my-token" },
 * );
 */
export declare const sendRawRequest: (baseUrl: string, values: SendRawRequestValues, authorizationHeaders?: Record<string, string>) => Promise<AxiosResponse>;
/**
 * Builds a pre-configured "Raw Request" action for a custom connector.
 * This action exposes a full HTTP interface (method, URL, headers, query
 * params, body) so integration builders can make arbitrary API calls.
 *
 * @param baseUrl The base URL of the API you're integrating with.
 * @param label The display label for the action. Defaults to `"Raw Request"`.
 * @param description The display description for the action. Defaults to `"Issue a raw HTTP request"`.
 * @returns An action definition for the raw request action.
 * @see {@link https://prismatic.io/docs/integrations/low-code-integration-designer/raw-request-actions/#building-an-http-raw-request-action-in-your-custom-component | Raw Request Actions}
 * @example
 * import { buildRawRequestAction } from "@prismatic-io/spectral/dist/clients/http";
 *
 * // Add a raw request action to your component
 * const actions = {
 *   listItems: action({ ... }),
 *   rawRequest: buildRawRequestAction("https://api.acme.com/v2"),
 * };
 */
export declare const buildRawRequestAction: (baseUrl: string, label?: string, description?: string) => import("../..").ActionDefinition<{
    url: {
        label: string;
        placeholder: string;
        type: "string";
        required: true;
        comments: string;
        example: string;
        clean: (value: unknown) => string;
    };
    method: {
        label: string;
        type: "string";
        required: true;
        model: {
            label: import("axios").Method;
            value: import("axios").Method;
        }[];
        comments: string;
        clean: (value: unknown) => string;
    };
    data: {
        label: string;
        placeholder: string;
        type: "string";
        required: false;
        comments: string;
        example: string;
    };
    formData: {
        label: string;
        placeholder: string;
        type: "string";
        collection: "keyvaluelist";
        required: false;
        comments: string;
        example: string;
    };
    fileData: {
        label: string;
        placeholder: string;
        type: "string";
        collection: "keyvaluelist";
        required: false;
        comments: string;
        example: string;
    };
    fileDataFileNames: {
        label: string;
        placeholder: string;
        type: "string";
        collection: "keyvaluelist";
        required: false;
        comments: string;
        clean: (values: any) => Record<string, string> | undefined;
    };
    queryParams: {
        label: string;
        placeholder: string;
        type: "string";
        collection: "keyvaluelist";
        required: false;
        comments: string;
    };
    headers: {
        label: string;
        placeholder: string;
        type: "string";
        collection: "keyvaluelist";
        required: false;
        comments: string;
        example: string;
    };
    responseType: {
        label: string;
        placeholder: string;
        type: "string";
        default: string;
        required: true;
        comments: string;
        model: {
            label: import("axios").ResponseType;
            value: import("axios").ResponseType;
        }[];
        clean: (value: unknown) => import("axios").ResponseType;
    };
    timeout: {
        label: string;
        type: "string";
        required: false;
        comments: string;
        example: string;
        clean: (value: unknown) => number;
    };
    debugRequest: {
        label: string;
        type: "boolean";
        required: false;
        comments: string;
        clean: (value: unknown) => boolean;
    };
    retryDelayMS: {
        label: string;
        placeholder: string;
        type: "string";
        required: false;
        comments: string;
        default: string;
        clean: (value: unknown) => number;
    };
    retryAllErrors: {
        label: string;
        type: "boolean";
        default: string;
        required: false;
        comments: string;
        clean: (value: unknown) => boolean;
    };
    maxRetries: {
        label: string;
        placeholder: string;
        type: "string";
        required: false;
        comments: string;
        default: string;
        clean: (value: unknown) => number;
    };
    useExponentialBackoff: {
        label: string;
        type: "boolean";
        default: string;
        required: false;
        comments: string;
        clean: (value: unknown) => boolean;
    };
    connection: {
        label: string;
        type: "connection";
        required: true;
    };
}, import("../..").ConfigVarResultCollection, boolean, {
    data: any;
}>;
export { inputs };