@squidcloud/client/dist/internal-common/src/public-types/api.public-types.d.ts

A typescript implementation of the Squid client

import { FieldName } from './document.public-types';
/** Represents the HTTP methods supported by an API endpoint. */
export type HttpMethod = 'post' | 'get' | 'delete' | 'patch' | 'put';
/** An identifier string used to uniquely represent an API endpoint. */
export type ApiEndpointId = string;
/** Represents the location in an API request where a parameter can be found. */
export type ApiParameterLocation = 'query' | 'body' | 'header' | 'path';
/** Represents the location in an API response where a value can appear. */
export type ApiResponseParameterLocation = 'header' | 'body';
/** Specifies the allowed locations where injection parameters can be inserted into the API request. */
export type ApiInjectionParameterLocation = 'header' | 'query';
/** A string path used to locate a specific field in a response structure. */
export type FieldPath = string;
/** A map of API endpoint definitions keyed by unique endpoint IDs. */
export type IntegrationApiEndpoints = Record<ApiEndpointId, ApiEndpoint>;
/** Describes a field included in an API request, including its location, optional description, and whether it is required. */
export interface ApiRequestField {
    /** The location of the field in the API request (e.g., query, body, header, path). */
    location: ApiParameterLocation;
    /** An optional description of the field's purpose or usage. */
    description?: string;
    /** Indicates whether the field is mandatory for the request. */
    required?: boolean;
}
/** The options for calling an API. */
export interface CallApiOptions {
    /** If true, the response will be returned as-is without any processing. */
    nativeResponse?: boolean;
    /**
     * An optional string to override the default origin of the API (e.g. `https://host:port`). Useful for
     * scenarios such as testing, development, or accessing the API from different environments.
     */
    originOverride?: string;
}
/** A native API call response. */
export interface NativeApiCallResponse<BodyType = unknown> {
    /** The response body, typed according to the expected content. */
    body: BodyType;
    /** A record of HTTP headers returned in the response. */
    headers: Record<string, string>;
    /** The HTTP status code of the response. */
    status: number;
}
/** Describes a field included in an API response, optionally including the field path and a description. */
export interface ApiResponseField {
    /** The location of the field in the API response (e.g., header, body). */
    location: ApiResponseParameterLocation;
    /** The path to the field within the response structure, if applicable. */
    path?: FieldPath;
    /** An optional description of the field's content or purpose. */
    description?: string;
}
/** Represents the possible values for injected field types used in request modification (e.g., secret or regular). */
export declare const API_INJECTION_FIELD_TYPES: readonly ["secret", "regular"];
/** The type of value to inject into an API request, such as a secret or a regular value. */
export type ApiInjectionFieldType = (typeof API_INJECTION_FIELD_TYPES)[number];
/** Defines a value to be injected into the API call, such as a secret or query parameter, along with its location and type. */
export interface ApiInjectionField {
    /** The value to be injected into the request. */
    value: string;
    /** The type of the injected value, either 'secret' or 'regular'. */
    type: ApiInjectionFieldType;
    /** The location in the request where the value should be injected (e.g., header, query). */
    location: ApiInjectionParameterLocation;
}
/** Connection options for interacting with a GraphQL API. */
export interface GraphQLConnectionOptions {
    /** The base URL of the GraphQL API endpoint. */
    baseUrl: string;
    /** An optional schema defining fields to inject into the GraphQL request. */
    injectionSchema?: ApiInjectionSchema;
}
/** A mapping of field names to their corresponding injection field definitions. */
export type ApiInjectionSchema = Record<FieldName, ApiInjectionField>;
/** Options for discovering APIs via an OpenAPI specification. */
export interface OpenApiDiscoveryOptions {
    /** The URL of the OpenAPI specification document. */
    openApiSpecUrl: string;
}
/** Represents the structure of an API endpoint, including its path, method, schemas, and metadata. */
export interface ApiEndpoint {
    /** The relative path of the endpoint (e.g., '/users'). */
    relativePath: string;
    /** The HTTP method used by the endpoint (e.g., 'get', 'post'). */
    method: HttpMethod;
    /** A schema defining the fields expected in the request, if any. */
    requestSchema?: Record<FieldName, ApiRequestField>;
    /** A schema defining the fields returned in the response, if any. */
    responseSchema?: Record<FieldPath, ApiResponseField>;
    /** A schema defining fields to inject into the request, if any. */
    injectionSchema?: ApiInjectionSchema;
    /** An optional array of tags categorizing the endpoint. */
    tags?: Array<string>;
    /** An optional description of the endpoint's purpose or behavior. */
    description?: string;
    /** The MIME type of the request body, if applicable (e.g., 'application/json'). */
    bodyMimeType?: string;
    /** Indicates whether the request body is mandatory for the endpoint. */
    isRequestBodyRequired?: boolean;
}