@squidcloud/client 1.0.492 → 1.0.493

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

@@ -0,0 +1,193 @@
+import { AiQueryOptions } from '../public-types/ai-query.public-types';
+import { IntegrationId } from '../public-types/communication.public-types';
+import { CollectionName, DocumentData, FieldName } from '../public-types/document.public-types';
+import { FieldSort, Operator, Query, SimpleCondition } from '../public-types/query.public-types';
+import { DeepRecord, FieldOf, PartialBy, Paths } from '../public-types/typescript.public-types';
+/**
+ * The information provided to the secureAiQuery function about the AI query being executed.
+ * @category AI
+ */
+export interface AiQueryContext {
+    /** The prompt provided for the AI query. */
+    prompt: string;
+    /** The options used for executing the AI query. */
+    options: AiQueryOptions;
+}
+/**
+ * Represents the Squid query context.
+ * Passed to methods that require query details, such as those annotated with the `@secureCollection` annotation.
+ * @category Database
+ */
+export declare class QueryContext<T extends DocumentData = any> {
+    readonly query: Query<T>;
+    /**
+     * The ID of the integration being queried.
+     */
+    get integrationId(): IntegrationId;
+    /**
+     * The name of the collection being queried.
+     */
+    get collectionName(): CollectionName;
+    /**
+     * The query limit if one exists, -1 otherwise.
+     */
+    get limit(): number;
+    /**
+     * The fields to project (include) in query results, or undefined if all fields should be returned.
+     */
+    get projectFields(): Array<FieldName> | undefined;
+    /**
+     * Verifies that the query's sort order aligns with the provided field sorts. The fields specified in the `sorts`
+     * parameter must appear in the exact order at the beginning of the query's sort sequence. The query can include
+     * additional fields in its sort order, but only after the specified sorts.
+     *
+     * @param sorts An array of field sorts.
+     * @returns Whether the query's sorts matches the provided field sorts.
+     */
+    sortedBy(sorts: Array<PartialBy<FieldSort<T>, 'asc'>>): boolean;
+    /**
+     * Verifies that the query's sort order exactly matches the provided field sorts. The fields specified in the
+     * `sorts` parameter must appear in the exact order in the query's sort sequence. No additional sorts may be present
+     * in the query.
+     *
+     * @param sorts An array of field sorts.
+     * @returns Whether the query's sorts exactly match the provided field sorts.
+     */
+    sortedByExact(sorts: Array<PartialBy<FieldSort<T>, 'asc'>>): boolean;
+    /**
+     * Verifies that the query is a subquery of the specified condition. A subquery is defined as a query that evaluates
+     * to a subset of the results that would be obtained by applying the parent condition. The subquery may also include
+     * additional conditions, as these only narrow the result set.
+     *
+     * @param fieldName The name of the field for the condition.
+     * @param operator The operator of the condition.
+     * @param value The value of the condition.
+     * @returns Whether the query is a subquery of the parent condition.
+     */
+    isSubqueryOf<F extends Paths<T>, O extends AllOperators>(fieldName: F, operator: O, value: GenericValue<T, F, O> | null): boolean;
+    /**
+     * Verifies that the query is a subquery of the specified condition. A subquery is defined as a query that evaluates
+     * to a subset of the results that would be obtained by applying the parent condition. The subquery may also include
+     * additional conditions, as these only narrow the result set.
+     *
+     * @param condition The condition to validate.
+     * @returns Whether the query is a subquery of the parent condition.
+     */
+    isSubqueryOfCondition(condition: GeneralCondition<T>): boolean;
+    /**
+     * Verifies that the query is a subquery of the specified conditions. A subquery is defined as a query that evaluates
+     * to a subset of the results that would be obtained by applying the parent conditions. The subquery may also include
+     * additional conditions, as these only narrow the result set.
+     *
+     * @param conditions The conditions to validate.
+     * @returns Whether the query includes subquery of the parent conditions.
+     */
+    isSubqueryOfConditions(conditions: GeneralConditions<T>): boolean;
+    /**
+     * Verifies that the query is a subquery of the specified query. A subquery is defined as a query that evaluates
+     * to a subset of the results that obtained for the parent query, including sorts and limits.
+     *
+     * @param query The query to validate.
+     * @returns Whether the query is a subquery of the parent query.
+     */
+    isSubqueryOfQuery(query: Query<T>): boolean;
+    /**
+     * Checks if this query's projectFields are a subset of the parent query's projectFields.
+     * A query can only be a child of another if the parent provides all fields the child needs.
+     *
+     * @param childFields - The projectFields of this query (the potential child)
+     * @param parentFields - The projectFields of the candidate parent query
+     * @returns Whether the child's fields are available from the parent
+     */
+    private isProjectFieldsSubset;
+    /**
+     * Returns all conditions that apply to any of the specified field names. This method
+     * provides a convenient way to retrieve all conditions that involve a specific set of fields.
+     *
+     * @param fieldNames The field names for which to retrieve conditions.
+     * @returns An array of conditions that involve any of the specified field names.
+     */
+    getConditionsFor<K extends Paths<T>>(...fieldNames: Array<K>): ContextConditions<T, K>;
+    /**
+     * Returns all conditions that apply to the specified field name. This method provides
+     * a convenient way to retrieve all conditions that involve a specific field.
+     *
+     * @param fieldName The field name for which to retrieve conditions.
+     * @returns An array of conditions that involve the specified field name.
+     */
+    getConditionsForField<K extends Paths<T>>(fieldName: K): ContextConditions<T>;
+    /**
+     * Returns true if the given document can be a result of the query.
+     * The method does not account for limit and sort order.
+     */
+    documentMatchesQuery(doc: DocumentData): boolean;
+}
+/**
+ * A list of context conditions.
+ * @category Database
+ */
+export type ContextConditions<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = Array<ContextCondition<Doc, F>>;
+/**
+ * A Context condition - a condition that replaces multiple '==' or '!=' conditions with 'in' and 'not in'.
+ * @category Database
+ */
+export type ContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = InContextCondition<Doc, F> | NotInContextCondition<Doc, F> | OtherContextCondition<Doc, F>;
+/**
+ * A condition using the 'in' operator to match values within a set.
+ * @category Database
+ */
+export interface InContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, 'in'> {
+    /** Specifies the 'in' operator to check if a value exists within an array. */
+    operator: 'in';
+    /** An array of values to match against the field. */
+    value: Array<FieldOf<DeepRecord<Doc>, Paths<Doc>> | any>;
+}
+/**
+ * A condition using the 'not in' operator to exclude values within a set.
+ * @category Database
+ */
+export interface NotInContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, 'not in'> {
+    /** Specifies the 'not in' operator to check if a value does not exist within an array. */
+    operator: 'not in';
+    /** An array of values to exclude from the field. */
+    value: Array<FieldOf<DeepRecord<Doc>, Paths<Doc>> | any>;
+}
+/**
+ * A condition using operators other than 'in' or 'not in' for field comparisons.
+ * @category Database
+ */
+export interface OtherContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, Exclude<ContextOperator, 'in' | 'not in'>> {
+    /** The operator to use for the comparison, excluding 'in' and 'not in'. */
+    operator: Exclude<ContextOperator, 'in' | 'not in'>;
+    /** The value to compare against the field. */
+    value: FieldOf<DeepRecord<Doc>, Paths<Doc>> | any;
+}
+/**
+ * A condition that includes all operators, including 'in' and 'not in', for general use.
+ * @category Database
+ */
+export interface GeneralCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, AllOperators> {
+    /** The operator to apply to the condition, including all possible operators. */
+    operator: AllOperators;
+    /** The value to use in the condition comparison. */
+    value: any;
+}
+/**
+ * A list of general conditions.
+ * @category Database
+ */
+export type GeneralConditions<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = Array<GeneralCondition<Doc, F>>;
+/**
+ * @category Database
+ */
+export type ContextOperator = Exclude<Operator, '==' | '!='> | 'in' | 'not in';
+/**
+ * Set of operators supported by query context conditions, including list membership.
+ * @category Database
+ */
+export type AllOperators = Operator | 'in' | 'not in';
+/**
+ * A generic value that can exist in a query.
+ * @category Database
+ */
+export type GenericValue<Doc = any, F extends Paths<Doc> = Paths<Doc>, O extends AllOperators = any> = O extends 'in' ? Array<DeepRecord<Doc>[F]> | null : O extends 'not in' ? Array<DeepRecord<Doc>[F]> | null : DeepRecord<Doc>[F] | null;

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

@@ -0,0 +1,302 @@
+import { AgentContextRequest, AiAgent, AiAgentContext, AiAgentMcpServerConfig, AiAnnotation, AiAudioCreateSpeechOptions, AiChatMessage, AiChatOptions, AiGenerateImageOptions, AllAiAgentChatOptions, ApplicationAiSettings, BuildAgentOptions } from '../public-types/ai-agent.public-types';
+import { AiProviderType, ModelIdSpec } from '../public-types/ai-common.public-types';
+import { AiContextMetadata, AiContextMetadataFilter } from '../public-types/ai-knowledge-base.public-types';
+import { AiAgentId, AiKnowledgeBaseId, AppId, ClientRequestId } from '../public-types/communication.public-types';
+import { JobId } from '../public-types/job.public-types';
+import { SecretKey } from '../public-types/secret.public-types';
+/** Specification for an AI model, defining its operational parameters. */
+export type AiModelSpec = {
+    /** 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;
+};
+export interface AiChatRequest {
+    agentId: AiAgentId;
+    clientRequestId: ClientRequestId;
+    prompt?: string;
+    options?: AllAiAgentChatOptions;
+    jobId: JobId;
+}
+export interface AiAskRequest {
+    agentId: AiAgentId;
+    prompt?: string;
+    options?: AllAiAgentChatOptions;
+    jobId: JobId;
+}
+export interface AiGenerateImageRequest {
+    prompt: string;
+    options: AiGenerateImageOptions;
+}
+export interface AiAskQuestionInternalRequest {
+    appId: AppId;
+    prompt: string;
+    options: AiChatOptions;
+    /**
+     * API key resolution mode (see `AiProviderFactory.getChatProviderForModel`). 'system' is
+     * required to resolve system-internal models (e.g. the 'openai-compatible' registry models)
+     * and makes the call billable to Squid, not the app. Defaults to 'auto'. The endpoint is
+     * `@Internal()`, so only internal-key callers can set this.
+     */
+    keyType?: 'auto' | 'system';
+}
+export interface AiAskQuestionInternalResponse {
+    answer: string;
+}
+export interface GetSharedAgentsInternalRequest {
+    organizationId: string;
+}
+export interface GetSharedAgentsInternalResponse {
+    sharedAgents: Array<{
+        agentId: AiAgentId;
+        appId: AppId;
+    }>;
+}
+export interface ClearSharedAgentsForOrgInternalRequest {
+    organizationId: string;
+}
+export interface AiContextSizeRequest {
+    appId: AppId;
+    agentId: AiAgentId;
+}
+export interface AiContextSizeResponse {
+    sizeBytes: number;
+}
+export interface AiAskResponse {
+    responseString: string;
+    annotations?: Record<string, AiAnnotation>;
+}
+export interface AiAskWithVoiceResponse {
+    responseString: string;
+    voiceResponse: AiAudioCreateSpeechResponse;
+    annotations?: Record<string, AiAnnotation>;
+}
+export interface AiTranscribeAndAskWithVoiceResponse {
+    transcribedPrompt: string;
+    responseString: string;
+    voiceResponse: AiAudioCreateSpeechResponse;
+    annotations?: Record<string, AiAnnotation>;
+}
+export interface AiTranscribeAndChatResponse {
+    transcribedPrompt: string;
+}
+export interface AiAudioCreateSpeechResponse {
+    mimeType: string;
+    extension: string;
+    base64File: string;
+}
+export interface AiAudioCreateSpeechRequest {
+    input: string;
+    options: AiAudioCreateSpeechOptions;
+}
+export interface GetAgentRequest {
+    agentId: AiAgentId;
+}
+export interface GetAgentResponse {
+    agent: AiAgent | undefined;
+}
+export interface GetAgentContextRequest {
+    agentId: AiAgentId;
+    contextId: string;
+}
+export interface ConnectAgentKnowledgeBaseRequest {
+    agentId: AiAgentId;
+    knowledgeBaseId: AiKnowledgeBaseId;
+    description: string;
+}
+export interface DisconnectAgentKnowledgeBaseRequest {
+    agentId: AiAgentId;
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+export interface DeleteAgentRequest {
+    agentId: AiAgentId;
+}
+export interface UnshareAgentRequest {
+    agentId: AiAgentId;
+}
+export interface SetAgentOptionInPathRequest {
+    agentId: AiAgentId;
+    path: string;
+    value: unknown;
+}
+export interface AddConnectedIntegrationRequest {
+    agentId: AiAgentId;
+    integrationId: string;
+    integrationType: string;
+    description: string;
+}
+export interface AddConnectedAgentRequest {
+    agentId: AiAgentId;
+    connectedAgentId: string;
+    description: string;
+}
+export interface AddConnectedKnowledgeBaseRequest {
+    agentId: AiAgentId;
+    knowledgeBaseId: string;
+    description: string;
+    /** Mirrors {@link AiConnectedKnowledgeBaseMetadata.includeMetadata}; forwarded so this atomic API honors it. */
+    includeMetadata?: boolean;
+}
+export interface AddFunctionRequest {
+    agentId: AiAgentId;
+    functionId: string;
+}
+export interface RemoveConnectedAgentRequest {
+    agentId: AiAgentId;
+    connectedAgentId: string;
+}
+export interface RemoveConnectedIntegrationRequest {
+    agentId: AiAgentId;
+    integrationId: string;
+}
+export interface RemoveConnectedKnowledgeBaseRequest {
+    agentId: AiAgentId;
+    knowledgeBaseId: string;
+}
+export interface RemoveFunctionRequest {
+    agentId: AiAgentId;
+    functionId: string;
+}
+export interface SetAgentDescriptionRequest {
+    agentId: AiAgentId;
+    description: string;
+}
+export interface SetAgentMcpServerRequest {
+    agentId: AiAgentId;
+    mcpServer: AiAgentMcpServerConfig;
+}
+export interface ListAgentContextsRequest {
+    agentId: AiAgentId;
+}
+export interface ListAgentContextsResponse {
+    contexts: Array<AiAgentContext>;
+}
+export interface DeleteAgentContextsRequest {
+    agentId: AiAgentId;
+    contextIds: Array<string>;
+}
+export interface UpsertAgentContextsRequest {
+    agentId: AiAgentId;
+    contextRequests: Array<AgentContextRequest>;
+}
+export interface UpsertAgentCustomGuardrailsRequest {
+    agentId: AiAgentId;
+    customGuardrail: string;
+}
+export interface DeleteAgentCustomGuardrailsRequest {
+    agentId: AiAgentId;
+}
+export interface ListAgentsResponse {
+    agents: Array<AiAgent>;
+}
+export interface GetApplicationAiSettingsResponse {
+    settings: ApplicationAiSettings;
+}
+export interface GetApplicationAiSettingsResponse {
+    settings: ApplicationAiSettings;
+}
+export interface SetApplicationAiSettingsRequest {
+    settings: ApplicationAiSettings;
+}
+export interface SetAiProviderApiKeySecretRequest {
+    providerType: AiProviderType;
+    secretKey: SecretKey | undefined;
+}
+export interface SetAiProviderApiKeySecretResponse {
+    settings: ApplicationAiSettings;
+}
+export interface ListChatModelsResponse {
+    models: ModelIdSpec[];
+}
+export interface RegenerateAgentApiKeyRequest {
+    agentId: AiAgentId;
+}
+export interface GetAgentApiKeyRequest {
+    agentId: AiAgentId;
+}
+export declare function validateAiContextMetadata(metadata: AiContextMetadata): void;
+export declare function validateAiContextMetadataFilter(filter: AiContextMetadataFilter): void;
+export declare const METADATA_SERVICE_FUNCTION_NAME = "default:metadata";
+export interface GetChatHistoryRequest {
+    agentId: AiAgentId;
+    memoryId: string;
+}
+export interface GetChatHistoryResponse {
+    messages: Array<AiChatMessage>;
+}
+export interface ProvideAgentFeedbackRequest {
+    agentId: string;
+    feedback: string;
+    /** If true, proposed changes are stored for later admin review instead of being applied immediately. */
+    holdForReview?: boolean;
+    /** Arbitrary caller-supplied metadata to store alongside the feedback. Limited to 4096 bytes when serialized. */
+    metadata?: Record<string, unknown>;
+}
+/** A proposed agent-feedback change, stored instead of applied when `holdForReview` is set. */
+export interface AgentFeedbackRecord {
+    id: string;
+    agentId: string;
+    integrationId?: string;
+    /** Name of the executable or aiFunction that produced this record, e.g. `provideAgentFeedback`. */
+    action: string;
+    params: Record<string, unknown>;
+    rawFeedback: string;
+    status: 'pending' | 'applied' | 'dismissed';
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ListAgentFeedbackRequest {
+    agentId: string;
+    limit?: number;
+    /** Cursor from a previous response's `nextCursor`, to fetch the next page. */
+    cursor?: string;
+    /** If set, only returns records with this status. */
+    status?: 'pending' | 'applied' | 'dismissed';
+}
+export interface ListAgentFeedbackResponse {
+    records: Array<AgentFeedbackRecord>;
+    nextCursor?: string;
+}
+/** Result of trying to apply or dismiss a single held-for-review feedback record. */
+export interface AgentFeedbackActionResult {
+    id: string;
+    success: boolean;
+    error?: string;
+}
+export interface ApplyAgentFeedbackRequest {
+    agentId: string;
+    ids: Array<string>;
+}
+export interface ApplyAgentFeedbackResponse {
+    results: Array<AgentFeedbackActionResult>;
+}
+export interface DismissAgentFeedbackRequest {
+    agentId: string;
+    ids: Array<string>;
+}
+export interface DismissAgentFeedbackResponse {
+    results: Array<AgentFeedbackActionResult>;
+}
+export interface BuildAgentRequest {
+    agentId: string;
+    request: string;
+    memoryId?: string;
+    options?: BuildAgentOptions;
+}
+export interface UploadAiFileRequest {
+    /** AI provider to upload file to. */
+    provider: AiProviderType;
+    /** Optional expiration time in seconds. If provided, file will be registered for automatic cleanup. */
+    expirationInSeconds?: number;
+}
+export interface UploadAiFileResponse {
+    fileId: string;
+}
+export interface DeleteAiFileRequest {
+    fileId: string;
+    /** AI provider that owns the file. */
+    provider: AiProviderType;
+}
+export interface DeleteAiFileResponse {
+    deleted: boolean;
+}