@squidcloud/client 1.0.472 → 1.0.474

package/dist/internal-common/src/metric-name.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Names of the Squid metrics.
+ *
+ * This list and its Kotlin counterpart (MetricName.kt) may diverge:
+ * each side declares only the metrics that its own backend emits.
+ * However, metrics emitted by both backends MUST use identical names on both sides —
+ * otherwise dashboards and metric queries that mix data from both sources will break.
+ *
+ * See MetricName.kt for documentation on each value.
+ */
+export declare const ALL_SQUID_METRIC_NAMES: readonly ["squid_functionExecution_count", "squid_functionExecution_time", "squid_aiChatbotContext_size", "squid_aiChatbotChatInputTokens_count", "squid_aiChatbotChatOutputTokens_count", "squid_aiChatbotChatReasoningTokens_count", "squid_aiChatbotChatCacheReadInputTokens_count", "squid_aiChatbotChatCacheWriteInputTokens_count", "squid_aiChatbotChatCostUsd_count", "squid_aiChatbotChatOutcome_count", "squid_aiImageGeneration_count", "squid_aiImageGeneration_time", "squid_aiRemoveBackground_count", "squid_aiRemoveBackground_time", "squid_aiAudioTranscribe_count", "squid_aiAudioTranscribe_time", "squid_aiAudioCreateSpeech_count", "squid_aiAudioCreateSpeech_time", "squid_aiIntegrationData_count", "squid_aiIntegrationData_time", "squid_aiIntegrationApi_count", "squid_aiIntegrationApi_time", "squid_apiControllerCall_count", "squid_apiControllerCall_time", "squid_aiContextUpsert_count", "squid_aiContextDelete_count", "squid_codeInitialization_count", "squid_codeInitialization_time", "squid_deleteApiKey_count", "squid_deleteApiKey_time", "squid_deleteSecret_count", "squid_deleteSecret_time", "squid_discoverGraphQLConnectionSchema_count", "squid_discoverGraphQLConnectionSchema_time", "squid_discoverOpenApiSchema_count", "squid_discoverOpenApiSchema_time", "squid_discoverOpenApiSchemaFromFile_count", "squid_discoverOpenApiSchemaFromFile_time", "squid_executeBackendFunction_count", "squid_executeBackendFunction_time", "squid_getAiChatbotProfiles_count", "squid_getAiChatbotProfiles_time", "squid_getAllApiKeys_count", "squid_getAllApiKeys_time", "squid_getAllSecrets_count", "squid_getAllSecrets_time", "squid_getAppApiKey_count", "squid_getAppApiKey_time", "squid_getSecret_count", "squid_getSecret_time", "squid_graphql_count", "squid_graphql_time", "squid_graphqlQuery_count", "squid_graphqlQuery_time", "squid_integrationCount_value", "squid_mutate_count", "squid_mutate_time", "squid_metricQuery_count", "squid_metricQuery_time", "squid_metricReport_count", "squid_metricReport_time", "squid_nativeQuery_count", "squid_nativeQuery_time", "squid_openapi_count", "squid_openapi_time", "squid_produceTopicMessage_count", "squid_produceTopicMessage_time", "squid_query_count", "squid_query_time", "squid_registerQuery_count", "squid_registerQuery_time", "squid_rerankChunks_count", "squid_rerankChunks_time", "squid_schedulerJob_count", "squid_schedulerJob_time", "squid_eventHandler_count", "squid_eventHandler_time", "squid_schema_size", "squid_secrets_entries", "squid_storageDeleteFiles_count", "squid_storageDeleteFiles_time", "squid_storageGetDownloadUrl_count", "squid_storageGetDownloadUrl_time", "squid_storageGetFileMetadata_count", "squid_storageGetFileMetadata_time", "squid_storageListDirectoryContents_count", "squid_storageListDirectoryContents_time", "squid_storageUploadFile_count", "squid_storageUploadFile_time", "squid_subscribeToTopic_count", "squid_subscribeToTopic_time", "squid_testGraphQLConnection_count", "squid_testGraphQLConnection_time", "squid_testAgentProtocolConnection_count", "squid_testAgentProtocolConnection_time", "squid_trigger_count", "squid_trigger_time", "squid_upsertApiKey_count", "squid_upsertApiKey_time", "squid_upsertSecret_count", "squid_upsertSecret_time", "squid_vectorChunks_count", "squid_vectorChunks_time", "squid_webhook_count", "squid_webhook_time", "squid_acquireLock_count", "squid_acquireLock_time", "squid_releaseLock_count", "squid_releaseLock_time"];
+export type MetricName = (typeof ALL_SQUID_METRIC_NAMES)[number];
+/** Common prefix for all Squid metrics. */
+export declare const SQUID_METRIC_NAME_PREFIX = "squid_";

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

@@ -24,6 +24,23 @@ export interface AiAgentApiIntegrationOptions {
     verboseStatusUpdates?: boolean;
     /** If provided, this agent will be used to generate API calls. */
     generateApiCallAgentId?: AiAgentId;
+    /** Full AI API options for advanced configuration of the API call execution. */
+    aiApiOptions?: AiApiOptions;
+}
+/**
+ * Options for configuring AI API call execution.
+ * @category AI
+ */
+export interface AiApiOptions {
+    /**
+     * Custom instructions appended to the endpoint-selection, body-construction, and response-analysis prompts.
+     */
+    instructions?: string;
+    /**
+     * Maximum number of distinct API calls the AI is allowed to make for one
+     * user prompt. Default 4.
+     */
+    maxIterations?: number;
 }
 /**
  * Configuration options for AI agent MCP integration.

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

@@ -304,6 +304,11 @@ export interface AiConnectedKnowledgeBaseMetadata {
     description: string;
     /** Whether to include document metadata when providing KB search results to the agent. Defaults to false. */
     includeMetadata?: boolean;
+    /**
+     * When true, the chat agent gets a tool to enumerate/search this KB's metadata field values on
+     * demand. Off by default. (Chat surface only for now; MCP/CLI is not wired.)
+     */
+    enableMetadataInspection?: boolean;
 }
 /**
  * Quotas for a single AI chat prompt (`ask()` method call).
@@ -318,6 +323,13 @@ export interface AiChatPromptQuotas {
      * Default: 5.
      */
     maxAiCallStackSize: number;
+    /**
+     * Maximum wall-clock runtime, in seconds, of a single prompt for CLI-agent models
+     * (Claude Code, Codex). Optional override of the per-call self-kill deadline — mainly to
+     * tighten it for stricter runaway protection — clamped to [30, 1800]. Ignored for
+     * non-CLI-agent models. Default: the platform maximum (30 minutes).
+     */
+    maxRuntimeSeconds?: number;
 }
 /**
  * Options for AI agent execution plan, allowing the agent to plan what functionality to use (connected agents,
@@ -410,6 +422,16 @@ export interface BaseAiChatOptions {
     maxOutputTokens?: number;
     /** The context ID to use for the request. If not provided, the agent's default context will be used. */
     memoryOptions?: AiAgentMemoryOptions;
+    /**
+     * Names a shared working directory for CLI-backed agents (`claude-code`, `codex`). When set, the agent
+     * runs in `/data/workspaces/<sharedWorkspaceId>` on the app's shared storage, so files created in
+     * one ask persist and are visible to later asks reusing the same id — including across providers.
+     *
+     * Pass the same id consistently for a conversation; changing it points the agent at a different
+     * directory (and, for Claude Code, starts a fresh transcript). Must match `[A-Za-z0-9_-]` (1-200 chars).
+     * Ignored by non-CLI agents and when shared storage is unavailable (falls back to an ephemeral dir).
+     */
+    sharedWorkspaceId?: string;
     /** Whether to disable the whole context for the request. Default to false. */
     disableContext?: boolean;
     /**
@@ -542,10 +564,44 @@ export interface OpenAiChatOptions extends BaseAiChatOptions {
     model?: OpenAiChatModelName;
 }
 /**
- * AI reasoning effort: Unsupported values are mapped to the closest supported option.
+ * Canonical reasoning-effort levels, ordered from least to most effort. These are the values that
+ * have a defined position on the effort axis and therefore participate in clamping when a model does
+ * not support the exact requested level.
+ * @category AI
+ */
+export type CanonicalReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/**
+ * AI reasoning effort. Pass one of the canonical levels for portable, autocomplete-friendly usage, or
+ * a raw provider-native string when a model exposes a level outside the canonical set.
+ *
+ * Resolution against the selected model (see {@link ReasoningCapability}):
+ * - exact match with the model's capability -> used as-is (1:1);
+ * - canonical level the model lacks -> clamped to the nearest supported level (ties resolve downward);
+ * - unknown string the model cannot place on the axis -> dropped, so the model's own default applies,
+ *   with a warning;
+ * - model without a reasoning knob -> ignored, with a warning.
  * @category AI
  */
-export type AiReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
+export type AiReasoningEffort = CanonicalReasoningEffort | (string & {});
+/**
+ * Declares how a model exposes reasoning effort. Used as the single source of truth for resolving a
+ * requested {@link AiReasoningEffort} onto what the model natively accepts. When a request cannot be
+ * matched or clamped, no reasoning parameter is emitted and the model applies its own native default.
+ *
+ * - `none`: the model has no reasoning knob (e.g. it always reasons).
+ * - `levels`: the model accepts a fixed set of named levels (emitted as a string).
+ * - `budget`: the model accepts a token budget; each canonical level maps to a concrete integer.
+ * @category AI
+ */
+export type ReasoningCapability = {
+    kind: 'none';
+} | {
+    kind: 'levels';
+    supported: AiReasoningEffort[];
+} | {
+    kind: 'budget';
+    perLevel: Partial<Record<CanonicalReasoningEffort, number>>;
+};
 /**
  * Controls response length and detail level.
  * Use `low` for brief responses,`medium` for balanced detail, or `high` for comprehensive explanations.
@@ -563,7 +619,7 @@ export type AiVerbosityLevel = 'low' | 'medium' | 'high';
  * **Example:**
  * ```typescript
  * {
- *   model: 'claude-sonnet-4-6',
+ *   model: 'claude-sonnet-5',
  *   responseFormat: {
  *     type: 'json_schema',
  *     schema: {
@@ -639,6 +695,25 @@ export declare const AGENT_STATUS_TITLE_AGENT_RESPONSE = "Agent Response";
  * @category AI
  */
 export declare const AGENT_STATUS_TITLE_ACCESSING_KB = "Accessing Knowledge Base";
+/**
+ * Status update title broadcast when the agent invokes an AI function callable
+ * (a backend `@aiFunction`). Lets a caller detect that a function was actually
+ * called, independent of how the model renders the result in its final answer.
+ * @category AI
+ */
+export declare const AGENT_STATUS_TITLE_CALLING_AI_FUNCTION = "Calling AI Function";
+/**
+ * Status update title broadcast when the agent invokes a knowledge-base metadata-inspection callable
+ * (the opt-in `enableMetadataInspection` tool). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB}
+ * so a caller can tell a metadata-value inspection apart from an ordinary KB search.
+ * @category AI
+ */
+export declare const AGENT_STATUS_TITLE_INSPECTING_KB_METADATA = "Inspecting Knowledge Base Metadata";
+/**
+ * Status update title broadcast when the agent queries a spreadsheet file callable.
+ * @category AI
+ */
+export declare const AGENT_STATUS_TITLE_QUERYING_SPREADSHEET = "Querying Spreadsheet";
 /**
  * A status message from an AI agent operation.
  * @category AI
@@ -900,6 +975,12 @@ export interface UserAiAskResponse {
     inputTokens?: number;
     /** The number of output tokens generated by the AI agent. */
     outputTokens?: number;
+    /** Cached input tokens read from the prompt cache. Only set by providers that report it (e.g. claude-code). */
+    cacheReadInputTokens?: number;
+    /** Input tokens written to the prompt cache. Only set by providers that report it (e.g. claude-code). */
+    cacheWriteInputTokens?: number;
+    /** Total request cost in USD as reported by the provider. Only set by providers that compute it (e.g. claude-code). */
+    totalCostUsd?: number;
 }
 /** Represents an annotation in the AI response. */
 export type AiAnnotation = AiFileAnnotation;

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

@@ -34,17 +34,17 @@ export declare const GEMINI_CHAT_MODEL_NAMES: readonly ["gemini-3.1-pro", "gemin
  * Public Grok chat model names (active models only).
  * @category AI
  */
-export declare const GROK_CHAT_MODEL_NAMES: readonly ["grok-4", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
+export declare const GROK_CHAT_MODEL_NAMES: readonly ["grok-4.3", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
 /**
  * Public Anthropic chat model names (active models only).
  * @category AI
  */
-export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-haiku-4-5-20251001", "claude-opus-4-8", "claude-sonnet-4-6"];
+export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-haiku-4-5-20251001", "claude-opus-4-8", "claude-sonnet-5"];
 /**
  * The supported AI model names.
  * @category AI
  */
-export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.5-pro", "claude-haiku-4-5-20251001", "claude-opus-4-8", "claude-sonnet-4-6", "gemini-3.1-pro", "gemini-3.5-flash", "gemini-3.1-flash-lite", "grok-4", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
+export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.5-pro", "claude-haiku-4-5-20251001", "claude-opus-4-8", "claude-sonnet-5", "gemini-3.1-pro", "gemini-3.5-flash", "gemini-3.1-flash-lite", "grok-4.3", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
 /** Checks if the given model name is a global AI chat model name.  */
 export declare function isVendorAiChatModelName(modelName: unknown): modelName is VendorAiChatModelName;
 /**

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

@@ -31,6 +31,12 @@ export interface AiKnowledgeBase {
     embeddingModel: AiEmbeddingsModelSelection;
     /** The model name that should be used when asking questions of this knowledge base. */
     chatModel: AiChatModelSelection;
+    /**
+     * The vector store backend this knowledge base reads/writes from. Set at creation (defaulting to
+     * the server's `SQUID_DEFAULT_VECTOR_DB_TYPE`, otherwise `'postgres'`) and immutable thereafter.
+     * Optional on the read type for backwards compatibility with older records.
+     */
+    vectorDbType?: VectorDbType;
     /** The timestamp the knowledge base was last updated */
     updatedAt: Date;
 }
@@ -54,6 +60,12 @@ export interface AiKnowledgeBaseMetadataField {
      * Also, it will be used for auto filtering when a prompt is sent to an AI agent.
      */
     description?: string;
+    /**
+     * True when {@link description} was AI-generated (via `generateMetadataFieldDescriptions`). Undefined or
+     * false means the description was authored by a human or has not been generated yet; it clears back to
+     * false once a human edits the description.
+     */
+    descriptionGeneratedByAi?: boolean;
 }
 /**
  * A record of metadata key-value pairs for AI context, where values are primitive types or undefined.
@@ -93,6 +105,17 @@ export type AiContextMetadataAndFilter = MetadataAndFilter;
  * @deprecated Use {@link MetadataOrFilter} from `metadata-filter.public-types` instead.
  */
 export type AiContextMetadataOrFilter = MetadataOrFilter;
+/**
+ * Retrieval mode for a knowledge-base search.
+ * - `'vector'`: dense-only similarity.
+ * - `'hybrid'`: native fusion of dense + lexical (only distinct on backends with native fusion, e.g.
+ *   Mongo Atlas; on pgvector it degrades to dense + a legacy app-side keyword fallback).
+ * - `'keyword'`: embedding-free lexical retrieval; the mechanism is backend-specific — native Lucene BM25
+ *   on Mongo Atlas (ranked, term-optional: a partial-term query still matches), and a boolean substring
+ *   filter on pgvector (every term must appear literally; unranked).
+ * @category AI
+ */
+export type AiKnowledgeBaseSearchMode = 'vector' | 'hybrid' | 'keyword';
 /**
  * The options for the AI knowledgebase search method.
  * @category AI
@@ -118,10 +141,19 @@ export interface AiKnowledgeBaseChatOptions {
      *   (Mongo Atlas uses `$rankFusion`; backends without native fusion fall back to dense-only with
      *   the legacy app-side keyword fallback).
      * - `'vector'`: dense-only — skips native fusion even on backends that support it.
+     * - `'keyword'`: embedding-free lexical retrieval; the mechanism is backend-specific. On Mongo Atlas it
+     *   is native Lucene BM25 (`$search`): results are ranked by relevance and term-optional — a partial-term
+     *   query still returns its best matches. On Postgres it is a boolean substring filter (`ILIKE ALL`):
+     *   every whitespace-separated term must appear in a chunk as a literal, case-insensitive substring,
+     *   matched independently (order, adjacency and relevance are NOT considered), so results are unranked and
+     *   for broad terms the returned top-k is arbitrary. Both skip embedding, dense, reranking and the
+     *   app-side keyword fallback. Lets an agent (or an eval) target exact tokens — identifiers, names, codes
+     *   — that dense retrieval tends to miss.
      *
-     * Intended to let A/B evaluations compare dense-only vs hybrid retrieval on the same backend.
+     * Intended to let A/B evaluations compare dense-only, hybrid and boolean-keyword candidate generation
+     * on the same backend.
      */
-    searchMode?: 'vector' | 'hybrid';
+    searchMode?: AiKnowledgeBaseSearchMode;
     /**
      * Per-pipeline weights for native hybrid fusion (Mongo `$rankFusion.combination.weights`). Only
      * applies when `searchMode` is `'hybrid'` on a backend with native fusion; ignored otherwise.
@@ -321,10 +353,19 @@ export interface AiKnowledgeBaseSearchOptions {
      *   (Mongo Atlas uses `$rankFusion`; backends without native fusion fall back to dense-only with
      *   the legacy app-side keyword fallback).
      * - `'vector'`: dense-only — skips native fusion even on backends that support it.
+     * - `'keyword'`: embedding-free lexical retrieval; the mechanism is backend-specific. On Mongo Atlas it
+     *   is native Lucene BM25 (`$search`): results are ranked by relevance and term-optional — a partial-term
+     *   query still returns its best matches. On Postgres it is a boolean substring filter (`ILIKE ALL`):
+     *   every whitespace-separated term must appear in a chunk as a literal, case-insensitive substring,
+     *   matched independently (order, adjacency and relevance are NOT considered), so results are unranked and
+     *   for broad terms the returned top-k is arbitrary. Both skip embedding, dense, reranking and the
+     *   app-side keyword fallback. Lets an agent (or an eval) target exact tokens — identifiers, names, codes
+     *   — that dense retrieval tends to miss.
      *
-     * Intended to let A/B evaluations compare dense-only vs hybrid retrieval on the same backend.
+     * Intended to let A/B evaluations compare dense-only, hybrid and boolean-keyword candidate generation
+     * on the same backend.
      */
-    searchMode?: 'vector' | 'hybrid';
+    searchMode?: AiKnowledgeBaseSearchMode;
     /**
      * Per-pipeline weights for native hybrid fusion (Mongo `$rankFusion.combination.weights`). Only
      * applies when `searchMode` is `'hybrid'` on a backend with native fusion; ignored otherwise.
@@ -455,13 +496,6 @@ export type AiEmbeddingsModelWithOptionalFields = Omit<AiKnowledgeBase, 'chatMod
     chatModel?: AiKnowledgeBase['chatModel'];
     name?: string;
     embeddingModel?: AiEmbeddingsModelSelection;
-    /**
-     * The vector store backend for this knowledge base. Optional: when omitted, newly-created KBs use
-     * the server's default backend (`SQUID_DEFAULT_VECTOR_DB_TYPE`, otherwise `'postgres'`). The backend
-     * cannot be changed once the KB exists, so on re-upsert this must either be omitted or match the
-     * existing value.
-     */
-    vectorDbType?: VectorDbType;
 };
 /**
  * API request for deleting an AiKnowledgeBase
@@ -513,4 +547,25 @@ export interface ListAiKnowledgeBasesResponse {
     /** All AI knowledge bases defined for the application. */
     knowledgeBases: Array<AiKnowledgeBase>;
 }
+/** Request to AI-generate descriptions for a KB's metadata fields and return them (the caller persists). */
+export interface GenerateMetadataFieldDescriptionsRequest {
+    /** The id of the AiKnowledgeBase. */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** Limit generation to these fields; omitted ⇒ all declared fields. */
+    fieldNames?: string[];
+    /** When true, regenerate fields that already have a description; default false (fill empties only). */
+    overwriteExisting?: boolean;
+}
+/** Response for the AI-generated metadata field descriptions. */
+export interface GenerateMetadataFieldDescriptionsResponse {
+    /** The (re)generated fields with their new descriptions; not persisted — the caller saves them. */
+    fields: Array<GeneratedMetadataFieldDescription>;
+}
+/** A generated description for a single metadata field. */
+export interface GeneratedMetadataFieldDescription {
+    /** The name of the metadata field. */
+    name: string;
+    /** The AI-generated description for the field. */
+    description: string;
+}
 export {};

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

@@ -0,0 +1,12 @@
+/**
+ * List of all connector package names.
+ * To prevent automatic discovery && latest version sync in 'prod' add your connector package name to
+ * 'CONNECTOR_PACKAGES_TO_EXCLUDE_FROM_AUTO_SYNC' in ConnectorsService (console-backend).
+ * @category Platform
+ */
+export declare const CONNECTOR_IDS: readonly ["confluence", "cotomi", "essentials", "freshdesk", "github", "google_calendar", "google_drive", "hubspot", "sharepoint", "jira", "jira_jsm", "linear", "mail", "onedrive", "salesforce", "servicenow_csm", "slack", "teams", "ticketmind_companion", "zendesk"];
+/**
+ * Unique connector package name.
+ * @category Platform
+ */
+export type ConnectorId = (typeof CONNECTOR_IDS)[number];

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

@@ -0,0 +1,30 @@
+import { ApiOptions } from '../public-types/api-client.public-types';
+import { ApiEndpointId, HttpMethod } from '../public-types/api.public-types';
+import { IntegrationId } from '../public-types/communication.public-types';
+/** The headers of an API call. */
+export type ApiHeaders = Record<string, string | number | boolean>;
+/** The context of an API call. */
+export declare class ApiCallContext {
+    readonly integrationId: IntegrationId;
+    readonly endpointId: ApiEndpointId;
+    readonly url: string;
+    readonly method: HttpMethod;
+    readonly body: unknown;
+    readonly options: ApiOptions;
+}
+/**
+ * Represents a request to call an API through a specified integration and endpoint.
+ * Includes optional method override and additional request options.
+ */
+export interface CallApiRequest<BodyType = any> {
+    /** The identifier of the integration through which the API is called. */
+    integrationId: IntegrationId;
+    /** Target API endpoint to invoke. */
+    endpointId: ApiEndpointId;
+    /** Optional request payload. */
+    body?: BodyType;
+    /** Optional HTTP method override. Default is POST. */
+    overrideMethod?: HttpMethod;
+    /** Additional request options. */
+    options: ApiOptions;
+}

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

@@ -0,0 +1,148 @@
+import { SquidDocIdObj, SquidDocument } from '../public-types/document.public-types';
+import { Paths } from '../public-types/typescript.public-types';
+/**
+ * The mutation type.
+ * @category Database
+ */
+export declare const MUTATION_TYPES: readonly ["insert", "update", "delete"];
+/**
+ * @category Database
+ */
+export type MutationType = (typeof MUTATION_TYPES)[number];
+interface BaseMutation {
+    type: MutationType;
+    squidDocIdObj: SquidDocIdObj;
+}
+/**
+ * A mutation on a document.
+ * @category Database
+ */
+export type Mutation<T = any> = UpdateMutation<T> | InsertMutation<T> | DeleteMutation;
+/**
+ * Represents a delete mutation on a document.
+ * @category Database
+ */
+export interface DeleteMutation extends BaseMutation {
+    /** Specifies that the mutation is a deletion. */
+    type: 'delete';
+}
+/**
+ * Represents an update mutation on a document.
+ * @category Database
+ */
+export interface UpdateMutation<T = any> extends BaseMutation {
+    /** Specifies that the mutation is an update. */
+    type: 'update';
+    /** The updated properties */
+    properties: {
+        [key in keyof T & string]?: Array<PropertyMutation<T[key]>>;
+    };
+}
+/**
+ * Represents an insert mutation on a document.
+ * @category Database
+ */
+export interface InsertMutation<T = any> extends BaseMutation {
+    /** Specifies that the mutation is an insertion. */
+    type: 'insert';
+    /** The inserted document */
+    properties: T;
+}
+/**
+ * A representation of a single property update.
+ * @category Database
+ */
+export type PropertyMutation<Value = any> = ApplyNumericFnPropertyMutation | ApplyStringFnPropertyMutation | ValueUpdatePropertyMutation<Value> | RemovePropertyMutation;
+/**
+ * A value update property mutation.
+ * @category Database
+ */
+export interface ValueUpdatePropertyMutation<Value = any> {
+    /** Specifies that the mutation updates a value. */
+    type: 'update';
+    /** New value to be set. */
+    value: Value;
+}
+/**
+ * Applying a numeric function to a property.
+ * @category Database
+ */
+export interface ApplyNumericFnPropertyMutation {
+    /** Specifies that the mutation applies a numeric function. */
+    type: 'applyNumericFn';
+    /** Numeric function to apply. */
+    fn: 'increment';
+    /** Value to use in the numeric function. */
+    value: number;
+}
+/**
+ * A property update that removes a property from a document.
+ * @category Database
+ */
+export interface RemovePropertyMutation {
+    /** Specifies that the mutation removes a property. */
+    type: 'removeProperty';
+}
+interface ApplyExtendString {
+    /** Specifies that the mutation applies a string function. */
+    type: 'applyStringFn';
+    /** String function to extend the existing string. */
+    fn: 'extendString';
+    /** String value to append. */
+    value: string;
+}
+interface ApplyTrimString {
+    /** Specifies that the mutation applies a string function. */
+    type: 'applyStringFn';
+    /** String function to trim the existing string. */
+    fn: 'trim';
+}
+/**
+ * A property mutation that modifies a string.
+ * @category Database
+ */
+export type ApplyStringFnPropertyMutation = ApplyExtendString | ApplyTrimString;
+/**
+ * The before and after documents of a document change.
+ * @category Database
+ */
+export interface BeforeAndAfterDocs<T = SquidDocument> {
+    /** Document state before the mutation. */
+    before: T | undefined;
+    /** Document state after the mutation. */
+    after: T | undefined;
+}
+/**
+ * The mutation context that will be provided to the security function.
+ * @category Database
+ */
+export declare class MutationContext<T = any> {
+    readonly mutation: Mutation<T>;
+    readonly beforeAndAfterDocs: BeforeAndAfterDocs<T>;
+    readonly serverTimeStamp: Date;
+    /**
+     * Returns the state of the document before the mutation was applied.
+     */
+    get before(): T | undefined;
+    /**
+     * Returns the state of the document after the mutation was applied.
+     */
+    get after(): T | undefined;
+    /**
+     * Returns the type of the mutation (insert, update, or delete).
+     */
+    getMutationType(): MutationType;
+    /** Returns true if the mutation affects the provided path. */
+    affectsPath(path: Paths<T>): boolean;
+    /**
+     * Find all affected paths starting from a root path.
+     *
+     * @example
+     * doc before - { a: { b: 1, c: 2 }, d: 3 }
+     * doc after - { a: { b: 1, c: 3 }, d: 4 }
+     * doc.affectedPaths('a') // ['a.c']
+     */
+    affectedPaths(startingRoot?: Paths<T> | string): Array<Paths<T>>;
+    private checkPath;
+}
+export {};

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

@@ -0,0 +1,72 @@
+import { IntegrationId } from '../public-types/communication.public-types';
+/**
+ * Represents the type of native query request, either relational, elastic or MongoDB.
+ * @category Database
+ */
+export type NativeQueryRequestType = 'relational' | 'mongo' | 'elasticsearch' | 'pure';
+interface BaseNativeQueryContext {
+    /** Type of the native query request. */
+    type: NativeQueryRequestType;
+    /** Identifier for the integration. */
+    integrationId: IntegrationId;
+}
+/**
+ * Context for executing a relational database query.
+ * @category Database
+ */
+export interface RelationalNativeQueryContext extends BaseNativeQueryContext {
+    /** Specifies that the query is for a relational database. */
+    type: 'relational';
+    /** SQL query string to be executed. */
+    query: string;
+    /** Parameters to be used in the query. */
+    params: Record<string, any>;
+}
+/**
+ * Context for executing a MongoDB query.
+ * @category Database
+ */
+export interface MongoNativeQueryContext extends BaseNativeQueryContext {
+    /** Specifies that the query is for a Mongo database. */
+    type: 'mongo';
+    /** Name of the MongoDB collection to query. */
+    collectionName: string;
+    /** Array of aggregation pipeline stages. */
+    aggregationPipeline: Array<any | undefined>;
+}
+/**
+ * Context for executing an Elasticsearch query.
+ * @category Database
+ */
+export interface ElasticsearchNativeQueryContext {
+    /** Specifies that the query is for an Elasticsearch database. */
+    type: 'elasticsearch';
+    /** Elasticsearch index to query. */
+    index: string;
+    /** Elasticsearch query string. */
+    endpoint?: string;
+    /** HTTP method to use for the request. */
+    method?: 'GET' | 'POST';
+    /** Body of the request. */
+    body: Record<string, any>;
+    /** Headers to include in the request. */
+    integrationId: IntegrationId;
+}
+/**
+ * Context for executing a pure database query.
+ * @category Database
+ */
+export interface PureNativeQueryContext extends BaseNativeQueryContext {
+    /** Specifies that the query is for a relational database. */
+    type: 'pure';
+    /** SQL query string to be executed. */
+    query: string;
+    /** Parameters to be used in the query. */
+    params: Record<string, any>;
+}
+/**
+ * Union type representing either a relational or MongoDB native query context.
+ * @category Database
+ */
+export type NativeQueryContext = RelationalNativeQueryContext | MongoNativeQueryContext | ElasticsearchNativeQueryContext | PureNativeQueryContext;
+export {};