@squidcloud/client 1.0.471 → 1.0.472

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

@@ -473,6 +473,15 @@ export interface BaseAiChatOptions {
     executionPlanOptions?: AiAgentExecutionPlanOptions;
     /** An array of file URLs to include in the chat context. */
     fileUrls?: Array<AiFileUrl>;
+    /**
+     * Arbitrary client-defined annotations attached to this AI call for usage tracking.
+     * Reported as `annotation.<key>` tags on Squid AI usage metrics, so token usage can later be
+     * filtered and grouped by these values (e.g. `{ feature: 'support-bot', requestSource: 'mobile' }`).
+     * Inherited by nested calls to connected agents made while serving this call.
+     * Limits: at most 10 entries, keys up to 64 characters, values up to 256 characters;
+     * entries beyond the limits are dropped or truncated.
+     */
+    metricAnnotations?: Record<string, string>;
     /**
      * The level of reasoning effort to apply; defaults to model-specific value.
      * Effective only for models with reasoning.

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

@@ -40,7 +40,11 @@ export interface AiKnowledgeBase {
 export interface AiKnowledgeBaseMetadataField {
     /** The name of field.*/
     name: string;
-    /** The field data type - used for filtering. For array, only array of strings is supported. */
+    /**
+     * The field data type - used for validation and filtering. `date` values are normalized to integer
+     * epoch milliseconds at write time so range filters (`$gt`/`$lt`) work across vector store backends.
+     * `array` is not yet supported and is rejected at knowledge-base upsert time.
+     */
     dataType: 'string' | 'number' | 'boolean' | 'date' | 'array';
     /** Indicates if the field is required for knowledge base entries.*/
     required: boolean;
@@ -168,6 +172,13 @@ export interface AiKnowledgeBaseContext {
     sizeBytes: number;
     /** Metadata associated with the context. */
     metadata: AiContextMetadata;
+    /**
+     * Names of metadata fields whose stored values were machine-extracted from the content
+     * (driven by the knowledge base's `metadataFields` schema) rather than user-supplied.
+     * On re-upsert/replay, extracted values count as not-supplied (re-extracted fresh) while
+     * user-supplied values are preserved; consumers can also use this to caveat extracted values.
+     */
+    autoExtractedMetadataFields?: string[];
     /** Original request configuration for how the context content was processed. */
     requestConfig?: AgentContextRequest;
 }

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

@@ -0,0 +1,18 @@
+/**
+ * A generic event that can be emitted with `squid.events().emit` and handled by one or more
+ * subscribers declared with the backend `@eventHandler` decorator. Events are delivered over core's
+ * internal event stream (not the public queue API), at-least-once and with no ordering guarantee.
+ */
+export interface TriggerEvent<T = unknown> {
+    /** Unique event id (e.g. `generateUUID()`). */
+    id: string;
+    /** The event type. Determines which `@eventHandler` subscribers receive the event. */
+    type: string;
+    /** Arbitrary, JSON-serializable event payload. */
+    payload: T;
+}
+/** Request body for the `events/emit` core endpoint that publishes a `TriggerEvent`. */
+export interface EmitEventRequest<T = unknown> {
+    /** The event to emit. */
+    event: TriggerEvent<T>;
+}

package/dist/typescript-client/src/agent/ai-agent-client-reference.d.ts

@@ -23,6 +23,7 @@ export declare class AiAgentReference {
     private readonly socketManager;
     private readonly jobClient;
     private readonly backendFunctionManager;
+    private readonly getMetricAnnotations;
     /**
      * Retrieves metadata and configuration of the AI agent.
      */
@@ -238,6 +239,11 @@ export declare class AiAgentReference {
     private replaceFileTags;
     private askInternal;
     private chatInternal;
+    /**
+     * Merges the Squid-instance-level metric annotations under the per-call ones.
+     * Returns the options unchanged when no annotations are set anywhere.
+     */
+    private withMetricAnnotations;
     /**
      * Calls rpcManager post but with the agent api key if one was given during construction
      */

package/dist/typescript-client/src/agent/ai-agent-client.d.ts

@@ -22,6 +22,7 @@ export declare class AiAgentClient {
     private readonly socketManager;
     private readonly jobClient;
     private readonly backendFunctionManager;
+    private readonly getMetricAnnotations;
     private readonly ongoingChatSequences;
     /**
      * Retrieves an instance of AiAgentReference for a specific agent ID.

package/dist/typescript-client/src/ai-client.d.ts

@@ -20,6 +20,7 @@ export declare class AiClient {
     private readonly rpcManager;
     private readonly jobClient;
     private readonly backendFunctionManager;
+    private readonly getMetricAnnotations;
     private aiAgentClient?;
     private aiKnowledgeBaseClient?;
     /**

package/dist/typescript-client/src/events-client.d.ts

@@ -0,0 +1,21 @@
+import { TriggerEvent } from '../../internal-common/src/public-types/event.public-types';
+/**
+ * EventsClient provides methods for emitting generic events that are handled by backend functions
+ * declared with the `@eventHandler` decorator.
+ * @category Platform
+ */
+export declare class EventsClient {
+    private readonly rpcManager;
+    /**
+     * Emits a generic event delivered to every subscriber declared with `@eventHandler` for the same
+     * event type. Events are delivered durably/at-least-once with no ordering guarantee, so handlers
+     * should be idempotent and order-independent. Resolves once the event is enqueued, not once
+     * subscribers have handled it.
+     *
+     * Requires API key authentication — events are emitted only by trusted server-side code, so calls
+     * authenticated with a user token are rejected.
+     *
+     * @param event The event to emit, with a unique `id`, a `type`, and a `payload`.
+     */
+    emit<T>(event: TriggerEvent<T>): Promise<void>;
+}

package/dist/typescript-client/src/index.d.ts

@@ -25,6 +25,7 @@ export * from './document-identity.service';
 export * from './document-reference';
 export * from './document-reference.factory';
 export * from './document-store';
+export * from './events-client';
 export * from './execute-function-options';
 export * from './external-auth-client';
 export * from './extraction-client';

package/dist/typescript-client/src/public-types.d.ts

@@ -13,6 +13,7 @@ export * from '../../internal-common/src/public-types/code-executor.public-types
 export * from '../../internal-common/src/public-types/communication.public-types';
 export * from '../../internal-common/src/public-types/context.public-types';
 export * from '../../internal-common/src/public-types/document.public-types';
+export * from '../../internal-common/src/public-types/event.public-types';
 export * from '../../internal-common/src/public-types/external-auth/external-auth.public-types';
 export * from '../../internal-common/src/public-types/extraction.public-types';
 export * from '../../internal-common/src/public-types/http-status.public-types';

package/dist/typescript-client/src/squid.d.ts

@@ -4,6 +4,7 @@ import { ApiClient } from './api-client';
 import { CollectionReference } from './collection-reference';
 import { ConnectionDetails } from './connection-details';
 import { DistributedLock, DistributedLockOptions } from './distributed-lock.manager';
+import { EventsClient } from './events-client';
 import { ExecuteFunctionOptions } from './execute-function-options';
 import { ExternalAuthClient } from './external-auth-client';
 import { ExtractionClient } from './extraction-client';
@@ -129,8 +130,10 @@ export declare class Squid {
     private readonly queueManagerFactory;
     private readonly schedulerClient;
     private readonly notificationClient;
+    private readonly eventsClient;
     private readonly _appId;
     private readonly runtimeOptions;
+    private metricAnnotations?;
     /**
      * Creates a new instance of Squid with the given options.
      *
@@ -314,6 +317,14 @@ export declare class Squid {
      * Returns a set of AI specific clients.
      */
     ai(): AiClient;
+    /**
+     * Sets default metric annotations attached to every AI call made through this Squid instance.
+     * Annotations are reported as `annotation.<key>` tags on Squid AI usage metrics, so token usage
+     * can later be filtered and grouped by them (e.g. `{ feature: 'support-bot' }`).
+     * Per-call `metricAnnotations` in chat options are merged on top of these defaults.
+     * Pass `undefined` to clear. See `BaseAiChatOptions.metricAnnotations` for limits.
+     */
+    setMetricAnnotations(annotations: Record<string, string> | undefined): void;
     /**
      * Returns a set of functionality for interacting with jobs.
      */
@@ -350,6 +361,10 @@ export declare class Squid {
      * Returns a client for working with structured data extraction tools.
      */
     extraction(): ExtractionClient;
+    /**
+     * Returns a client for emitting events handled by `@eventHandler` backend functions.
+     */
+    events(): EventsClient;
     /**
      * Returns a distributed lock for the given mutex. The lock can be used to synchronize access to a shared resource.
      * The lock will be released when the release method on the returned object is invoked or whenever the connection

package/dist/typescript-client/src/version.d.ts

@@ -2,4 +2,4 @@
  * The current version of the SquidCloud client package.
  * @category Platform
  */
-export declare const SQUIDCLOUD_CLIENT_PACKAGE_VERSION = "1.0.471";
+export declare const SQUIDCLOUD_CLIENT_PACKAGE_VERSION = "1.0.472";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/client",
-  "version": "1.0.471",
+  "version": "1.0.472",
   "description": "A typescript implementation of the Squid client",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

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

@@ -1,14 +0,0 @@
-/**
- * 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_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_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-backend/api-call.public-context.d.ts

@@ -1,30 +0,0 @@
-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

@@ -1,148 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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 {};