@squidcloud/client 1.0.145-beta → 1.0.146-beta

package/dist/internal-common/src/public-types/ai-matchmaking.public-types.d.ts

@@ -0,0 +1,186 @@
+import { AiContextMetadata, AiContextMetadataFilter } from './ai-knowledge-base.public-types';
+/**
+ * Represents a category in the matchmaker.
+ * The description is used by the AI to extract features from the content.
+ * @category AI
+ */
+export interface MmCategory {
+    /** The unique identifier of the category. */
+    id: string;
+    /** A description used by the AI to understand and extract features from the category content. */
+    description: string;
+}
+/**
+ * Represents a matchmaker entity for a given category.
+ * The metadata is used to filter the entities when finding matches.
+ * @category AI
+ */
+export interface MmEntity {
+    /** The unique identifier of the entity. */
+    id: string;
+    /** The content of the entity to be matched. */
+    content: string;
+    /** The ID of the category this entity belongs to. */
+    categoryId: string;
+    /** Metadata used for filtering entities during matching. */
+    metadata: AiContextMetadata;
+}
+/**
+ * Represents a matchmaker.
+ * The description is used to describe the matchmaker and by the AI to better understand the domain.
+ * The categories represent the types of entities that can be matched (it is possible to match items in the same
+ * category).
+ * @category AI
+ */
+export interface MmMatchMaker {
+    /** The unique identifier of the matchmaker. */
+    id: string;
+    /** A description aiding the AI in understanding the matchmaker's domain. */
+    description: string;
+    /** An array of categories defining the types of entities that can be matched. */
+    categories: Array<MmCategory>;
+}
+/**
+ * Represents a matchmaker entity match. A high score indicates a good match.
+ * @category AI
+ */
+export interface MmEntityMatch extends MmEntity {
+    /** The score of the match, ranging from 0 to 100, where 100 is the best match. */
+    score: number;
+    /** The reasoning behind the match score, provided by the AI. */
+    reasoning: string;
+}
+/**
+ * Represents options for finding matches in the matchmaker system.
+ * @category AI
+ */
+export interface MmFindMatchesOptions {
+    /** Optional metadata filter conditions to narrow down matching entities; defaults to none. */
+    metadataFilter?: AiContextMetadataFilter;
+    /** The maximum number of matches to return; defaults to 100, with a maximum of 100. */
+    limit?: number;
+    /** The category ID to match entities against; defaults to the next or first category in the matchmaker. */
+    matchToCategoryId?: string;
+}
+/**
+ * Represents options for listing entities in the matchmaker system.
+ - * @category AI
+ */
+export interface MmListEntitiesOptions {
+    /** Optional metadata filter conditions to narrow down listed entities; defaults to none. */
+    metadataFilter?: AiContextMetadataFilter;
+    /** The maximum number of entities to return; defaults to 100. */
+    limit?: number;
+}
+/**
+ * API request to delete a matchmaker
+ * @category AI
+ */
+export interface MmDeleteMatchMakerRequest {
+    /** The ID of the matchmaker to delete */
+    matchMakerId: string;
+}
+/**
+ * API response for getting a matchmaker
+ * @category AI
+ */
+export interface MmGetMatchMakerResponse {
+    /** The matchmaker, if found */
+    matchMaker: MmMatchMaker | undefined;
+}
+/**
+ * API request to delete an entity
+ * @category AI
+ */
+export interface MmDeleteEntityRequest {
+    /** The ID of the matchmaker */
+    matchMakerId: string;
+    /** The ID of the entity to delete */
+    entityId: string;
+}
+/**
+ * API request to insert multiple entities
+ * @category AI
+ */
+export interface MmInsertEntitiesRequest {
+    /** The ID of the matchmaker */
+    matchMakerId: string;
+    /** Array of entities to insert */
+    entities: Array<MmEntity>;
+}
+/**
+ * API request to find matches for an entity
+ * @category AI
+ */
+export interface MmFindMatchesRequest {
+    /** The ID of the matchmaker */
+    matchMakerId: string;
+    /** The ID of the entity to find matches for */
+    entityId: string;
+    /** Options for finding matches */
+    options: MmFindMatchesOptions;
+}
+/**
+ * API response for finding matches
+ * @category AI
+ */
+export interface MmFindMatchesResponse {
+    /** Array of matching entities */
+    matches: Array<MmEntityMatch>;
+}
+/**
+ * API request to find matches for an entity not yet inserted
+ * @category AI
+ */
+export interface MmFindMatchesForEntityRequest {
+    /** The ID of the matchmaker */
+    matchMakerId: string;
+    /** The entity to find matches for */
+    entity: Omit<MmEntity, 'metadata' | 'id'>;
+    /** Options for finding matches */
+    options: MmFindMatchesOptions;
+}
+/**
+ * API response for finding matches for an entity
+ * @category AI
+ */
+export interface MmFindMatchesForEntityResponse {
+    /** Array of matching entities */
+    matches: Array<MmEntityMatch>;
+}
+/**
+ * API response for listing matchmakers
+ * @category AI
+ */
+export interface MmListMatchMakersResponse {
+    /** Array of matchmakers */
+    matchMakers: Array<MmMatchMaker>;
+}
+/**
+ * API request to list entities
+ * @category AI
+ */
+export interface MmListEntitiesRequest {
+    /** The ID of the matchmaker */
+    matchMakerId: string;
+    /** The ID of the category */
+    categoryId: string;
+    /** Options for listing entities */
+    options: MmListEntitiesOptions;
+}
+/**
+ * API response for listing entities
+ * @category AI
+ */
+export interface MmListEntitiesResponse {
+    /** Array of entities */
+    entities: Array<MmEntity>;
+}
+/**
+ * API response for getting an entity
+ * @category AI
+ */
+export interface MmGetEntityResponse {
+    /** The entity, if found */
+    entity: MmEntity | undefined;
+}

package/dist/internal-common/src/public-types/ai-query.public-types.d.ts

@@ -0,0 +1,170 @@
+import { AiChatOptions, AiSessionContext } from './ai-agent.public-types';
+import { ApiOptions } from './api-client.public-types';
+import { AiAgentId, IntegrationId } from './communication.public-types';
+/**
+ * Request to execute an AI query using a specific integration.
+ * Supports additional query execution options.
+ * @category AI
+ */
+export interface AiQueryRequest {
+    /** ID of the integration to execute the AI query. */
+    integrationId: IntegrationId;
+    /** User-provided prompt for the AI query. */
+    prompt: string;
+    /** Additional options for query execution. */
+    options?: AiQueryOptions;
+}
+/**
+ * Options for configuring AI query execution.
+ * Includes instructions, model overrides, and additional execution settings.
+ * @category AI
+ */
+export interface AiQueryOptions {
+    /**
+     * Custom instructions to modify AI query generation behavior.
+     * Used for all stages unless there is a per-stage override.
+     */
+    instructions?: string;
+    /** Whether to enable raw results output. */
+    enableRawResults?: boolean;
+    /** Whether to generate a step-by-step walkthrough for the response. */
+    generateWalkthrough?: boolean;
+    /** Options for the collection selection stage. */
+    selectCollectionsOptions?: AiQuerySelectCollectionsOptions;
+    /** Options for the query generation stage. */
+    generateQueryOptions?: AiQueryGenerateQueryOptions;
+    /** Options specify how to query result should be analyzed (processed) before returning it to user. */
+    analyzeResultsOptions?: AiQueryAnalyzeResultsOptions;
+    /** Session information for the AI query execution. */
+    sessionContext?: AiSessionContext;
+}
+/**
+ * Options for the collection selection stage.
+ *
+ * At this stage Squid selects a subset of collections that will be used by the later stage to generate the real query.
+ * It is recommended that the set of collections selected by this stage be broad enough so the query generation stage
+ * has a good view of the database.
+ */
+export interface AiQuerySelectCollectionsOptions {
+    /**
+     * Limits collections to be used in the query only to these collections.
+     * When not provided, all collections are used.
+     */
+    collectionsToUse?: string[];
+    /** Defines the stage algorithm. Default: 'auto'. */
+    runMode?: AiQueryCollectionsSelectionRunMode;
+    /** Used to customize AI agent behavior used by the stage. */
+    aiOptions?: AiChatOptions;
+}
+/**
+ * Defines the stage behavior:
+ * - 'default' - Squid will decide if to run the collection selection algorithm or not.
+ * - 'force' - Collection selection algorithm is run always, even if collectionsToUse are provided.
+ * - 'disable' - The stage is disabled. The whole schema (or collectionsToUse) will be passed to the next step.
+ */
+export type AiQueryCollectionsSelectionRunMode = 'default' | 'force' | 'disable';
+/**
+ * Options for the query generation stage.
+ *
+ * At this stage Squid generates the database native query based on the user prompt and a set of collections selected
+ * in the previous stage. */
+export interface AiQueryGenerateQueryOptions {
+    /** Customizes AI agent behavior used by the stage. */
+    aiOptions?: AiChatOptions;
+    /** Number of retries due to errors in a generated AI query. Default: 2. */
+    maxErrorCorrections?: number;
+    /**
+     * If provided, the AI Query process will use this agent to generate a query.
+     */
+    agentId?: AiAgentId;
+}
+/** Options for the query result analysis. */
+export interface AiQueryAnalyzeResultsOptions {
+    /** Enables or disables code interpreter mode. Default: 'false'. */
+    enableCodeInterpreter?: boolean;
+    /** Customizes AI agent behavior used by the stage. */
+    aiOptions?: AiChatOptions;
+    /**
+     * If provided, the AI Query process will use this agent to analyze the query result and provide the final answer.
+     */
+    agentId?: AiAgentId;
+}
+/**
+ * Response from an AI query execution.
+ * Contains the generated answer, optional explanation, and executed query details.
+ * @category AI
+ */
+export interface AiQueryResponse {
+    /** AI-generated answer for the query. */
+    answer: string;
+    /** Optional explanation for the AI-generated answer. */
+    explanation?: string;
+    /** Query executed by the AI, if applicable. */
+    executedQuery?: string;
+    /** Markdown format type of the executed query response. */
+    queryMarkdownType?: string;
+    /** URL to access raw results from the query execution. */
+    rawResultsUrl?: string;
+    /** Indicates whether the query execution was successful. */
+    success: boolean;
+}
+/**
+ * Details of an executed query, including the query text and result type.
+ * @category AI
+ */
+export interface ExecutedQuery {
+    /** Text of the executed query. */
+    query: string;
+    /** The Markdown type of the result (sql, mongo, etc.). */
+    markdownType: string;
+    /** URL to access raw results from the query execution. */
+    rawResultsUrl?: string;
+}
+/**
+ * Response from executing an AI query across multiple integrations.
+ * Includes answers and explanations for each executed query.
+ * @category AI
+ */
+export interface ExecuteAiQueryMultiResponse {
+    /** AI-generated answer for the multi-integration query. */
+    answer: string;
+    /** Optional explanation for the AI-generated response. */
+    explanation?: string;
+    /** List of executed queries with details. */
+    executedQueries: Array<ExecutedQuery>;
+    /** Indicates whether the query execution was successful. */
+    success: boolean;
+}
+/**
+ * The AI API call response
+ * @category AI
+ */
+export interface AiApiResult {
+    /** ID of the executed API endpoint. */
+    endpointId: string;
+    /** Name of the executed API endpoint. */
+    responseBody: string | object;
+    /** Status code of the executed API request. */
+    responseStatusCode: number;
+    /** Request's body of the executed API request. */
+    requestBody: any;
+    /** Request options of the executed API request. */
+    requestOptions: ApiOptions;
+}
+/**
+ * Response from executing an AI-powered API request.
+ * Includes the AI-generated answer and details of executed API calls.
+ * @category AI
+ */
+export interface ExecuteAiApiResponse {
+    /** AI-generated answer for the API request. */
+    answer: string;
+    /** Optional explanation for the AI-generated API response. */
+    explanation?: string;
+    /** List of executed API requests and their results. */
+    executedApis?: Array<AiApiResult>;
+    /** Markdown format type of the executed query response. */
+    queryMarkdownType?: string;
+    /** Indicates whether the API request execution was successful. */
+    success: boolean;
+}

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

@@ -0,0 +1,9 @@
+/** Optional configuration for an API call, including headers, query, and path parameters. */
+export interface ApiOptions {
+    /** Headers to include in the API request. */
+    headers?: Record<string, string | number | boolean>;
+    /** Query parameters to append to the API URL. */
+    queryParams?: Record<string, string | number | boolean>;
+    /** Path parameters to substitute in the API URL. */
+    pathParams?: Record<string, string | number | boolean>;
+}

package/dist/internal-common/src/public-types/api.public-types.d.ts

@@ -0,0 +1,91 @@
+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 InternalCallApiOptions {
+    /** 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;
+}
+/** 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;
+}

package/dist/internal-common/src/public-types/backend.public-types.d.ts

@@ -0,0 +1,50 @@
+/** Backend related public types that should be available on the client SDK */
+/** A type alias for a string that represents an AI function ID. */
+export type AiFunctionId = string;
+/** A type alias for a string that represents an AI functions configurator ID. */
+export type AiFunctionsConfiguratorId = string;
+/**
+ * A type alias for a service identifier.
+ * @category Queue
+ */
+export type TopicName = string;
+/** A type alias for a service class name. */
+export type ServiceName = string;
+/** A type alias for a function name within a service. */
+export type FunctionName = string;
+/**
+ * Function name with contextual data, where the data must be serializable as JSON.
+ */
+export interface AiFunctionIdWithContext {
+    /**
+     * The ID of the AI function as described in @aiFunction decorator.
+     * Historically named as 'name' because AI function name is the default value for 'ID'.
+     */
+    name: AiFunctionId;
+    /** A record of contextual data associated with the function call. */
+    context?: Record<string, unknown>;
+    /** A list of predefined parameter values for the AI function. These parameters are hidden from the AI. */
+    predefinedParameters?: Record<string, unknown>;
+}
+/**
+ * A combined service and function name in the format 'ServiceName:FunctionName'.
+ * Uniquely identifies a function within a service.
+ */
+export type ServiceFunctionName = `${ServiceName}:${FunctionName}`;
+/**
+ * LLM model name for use in API calls, eg. "gpt-4o-mini".
+ */
+export type UserAiChatModelName = string;
+/**
+ * Stats about a given LLM model.
+ */
+export type LlmModelMetadata = {
+    /**
+     * A friendly name for the model, to display in UIs.
+     */
+    displayName: string;
+    /** Maximum tokens the model can generate in a single response. */
+    maxOutputTokens: number;
+    /** Total context window size: input (aka prompt) + output (aka completion) tokens combined. */
+    contextWindowTokens: number;
+};

package/dist/{common/src/backend-function.schemas.d.ts → internal-common/src/public-types/code-executor.public-types.d.ts}

@@ -1 +1 @@
-export {};
+export {};

package/dist/internal-common/src/public-types/communication.public-types.d.ts

@@ -0,0 +1,30 @@
+/** A type alias for an application id. */
+export type AppId = string;
+/** A tuple of environment identifiers like 'dev' or 'prod'. */
+export declare const ENVIRONMENT_IDS: readonly ["dev", "prod"];
+/** A type representing valid environment identifiers derived from ENVIRONMENT_IDS. */
+export type EnvironmentId = (typeof ENVIRONMENT_IDS)[number];
+/** A type alias for a squid developer identifier. */
+export type SquidDeveloperId = string;
+/** A type alias for an integration id. */
+export type IntegrationId = string;
+/** A type alias for a client identifier. */
+export type ClientId = string;
+/** A type alias for a squid document identifier. */
+export type SquidDocId = string;
+/** A type alias for a client request identifier. */
+export type ClientRequestId = string;
+/** ID of AI agent. Also known as AI profile id. */
+export type AiAgentId = string;
+/** App-level ID of AI Knowledge Base */
+export type AiKnowledgeBaseId = string;
+/**
+ * The built-in agent id. Cannot be customized.
+ * @category AI
+ */
+export declare const BUILT_IN_AGENT_ID = "built_in_agent";
+/**
+ * A type alias for an AI context identifier.
+ * @category AI
+ */
+export type AiContextId = string;

package/dist/internal-common/src/public-types/context.public-types.d.ts

@@ -0,0 +1,83 @@
+import { AppId, ClientId } from './communication.public-types';
+/**
+ * @category Auth
+ */
+export type AuthType = 'Bearer' | 'ApiKey';
+/**
+ * The payload of a JWT token when Bearer authentication is used.
+ * @category Auth
+ */
+export interface AuthWithBearer {
+    /** Specifies the Bearer authentication type. */
+    type: 'Bearer';
+    /** The unique identifier of the authenticated user. */
+    userId: string;
+    /** The expiration timestamp of the token, in seconds. */
+    expiration: number;
+    /** Additional attributes associated with the token. */
+    attributes: Record<string, any>;
+    /** The raw JWT token string, if available. */
+    jwt?: string;
+}
+/**
+ * The authentication object for the current request when an API key is used.
+ * @category Auth
+ */
+export interface AuthWithApiKey {
+    /** Specifies the API key authentication type. */
+    type: 'ApiKey';
+    /** The API key string used for authentication. */
+    apiKey: string;
+}
+/**
+ * The authentication object for the current request.
+ * @category Auth
+ */
+export type Auth = AuthWithBearer | AuthWithApiKey;
+/**
+ * Represents an authentication token with its type and associated details.
+ * @category Auth
+ */
+export interface AuthToken {
+    /** The type of authentication (e.g., 'Bearer' or 'ApiKey'). */
+    type: AuthType;
+    /** The token string used for authentication. */
+    token: string;
+    /** The ID of the integration associated with the token, if applicable. */
+    integrationId?: string;
+}
+/** * The context of a request to a service, providing metadata about the request source. */
+export interface RunContext {
+    /** Your applicationId. */
+    appId: AppId;
+    /**
+     * The id of the client that initiated this request. This is only relevant in cases that the request was initiated by
+     * a client such as when securing an api call or a DB operation. This id will not be available for triggers,
+     * schedulers, webhooks and other functions that are not directly initiated by a user action.
+     */
+    clientId?: ClientId;
+    /** The IP address of the client that initiated this request. */
+    sourceIp?: string;
+    /** The headers of the request. Headers are in lower-case. */
+    headers?: Record<string, any>;
+    /** Additional context for OpenAPI requests */
+    openApiContext?: OpenApiContext;
+}
+/** In the case of OpenAPI, the context of the request is provided in a separate object. */
+export interface OpenApiContext {
+    /** The OpenAPI request. */
+    request: RawRequest;
+}
+/** Represents a raw HTTP request, including method, path, query parameters, body, and headers. */
+export interface RawRequest {
+    /** The HTTP method of the request (e.g., GET, POST, PUT, DELETE). */
+    method: string;
+    /** The path of the request, excluding the domain and query parameters. */
+    path: string;
+    /** The query parameters of the request, represented as key-value pairs. */
+    queryParams?: Record<string, string>;
+    /** The body of the request, if applicable. */
+    rawBody?: string;
+    /** The headers of the request, represented as key-value pairs. */
+    headers?: Record<string, string>;
+}