@squidcloud/client 1.0.470 → 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

@@ -2,6 +2,7 @@ import { AgentContextRequest, AiChatModelSelection, UpsertContextStatusError } f
 import { AiEmbeddingsModelSelection, AiRerankProvider } from './ai-common.public-types';
 import { AiContextId, AiKnowledgeBaseId, AppId } from './communication.public-types';
 import { DocumentExtractionMethod } from './extraction.public-types';
+import { MetadataAndFilter, MetadataFieldFilter, MetadataFilter, MetadataOrFilter, MetadataSimpleFilter, MetadataValue, MetadataValueArray } from './metadata-filter.public-types';
 /**
  * The set of supported vector store backends for a knowledge base. The authoritative backend for a
  * given KB is persisted on its record; reads/writes route through the matching vector provider.
@@ -39,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;
@@ -57,67 +62,37 @@ export interface AiKnowledgeBaseMetadataField {
 export type AiContextMetadata = Record<string, AiContextMetadataValue>;
 /**
  * @category AI
+ * @deprecated Use {@link MetadataValue} from `metadata-filter.public-types` instead.
  */
-export type AiContextMetadataValue = number | string | boolean | undefined;
+export type AiContextMetadataValue = MetadataValue;
 /**
  * @category AI
+ * @deprecated Use {@link MetadataValueArray} from `metadata-filter.public-types` instead.
  */
-export type AiContextMetadataValueArray = AiContextMetadataValue[];
-interface AiContextMetadataEqFilter {
-    $eq: AiContextMetadataValue;
-}
-interface AiContextMetadataNeFilter {
-    $ne: AiContextMetadataValue;
-}
-interface AiContextMetadataGtFilter {
-    $gt: number;
-}
-interface AiContextMetadataGteFilter {
-    $gte: number;
-}
-interface AiContextMetadataLtFilter {
-    $lt: number;
-}
-interface AiContextMetadataLteFilter {
-    $lte: number;
-}
-interface AiContextMetadataInFilter {
-    $in: AiContextMetadataValueArray;
-}
-interface AiContextMetadataNinFilter {
-    $nin: AiContextMetadataValueArray;
-}
-interface AiContextMetadataExistsFilter {
-    $exists: boolean;
-}
+export type AiContextMetadataValueArray = MetadataValueArray;
 /**
  * @category AI
+ * @deprecated Use {@link MetadataSimpleFilter} from `metadata-filter.public-types` instead.
  */
-export type AiContextMetadataSimpleFilter = AiContextMetadataEqFilter | AiContextMetadataNeFilter | AiContextMetadataGtFilter | AiContextMetadataGteFilter | AiContextMetadataLtFilter | AiContextMetadataLteFilter | AiContextMetadataInFilter | AiContextMetadataNinFilter | AiContextMetadataExistsFilter;
+export type AiContextMetadataSimpleFilter = MetadataSimpleFilter;
 /**
  * A filter for AI context metadata based on field-specific conditions or values.
  * @category AI
+ * @deprecated Use {@link MetadataFieldFilter} from `metadata-filter.public-types` instead.
  */
-export interface AiContextMetadataFieldFilter {
-    /** A record where keys are field names and values are either simple filters or direct metadata values. */
-    [field: string]: AiContextMetadataSimpleFilter | AiContextMetadataValue;
-}
+export type AiContextMetadataFieldFilter = MetadataFieldFilter;
 /**
  * A filter combining multiple AI context metadata filters with a logical AND operation.
  * @category AI
+ * @deprecated Use {@link MetadataAndFilter} from `metadata-filter.public-types` instead.
  */
-export interface AiContextMetadataAndFilter {
-    /** An array of filters that must all be true for the condition to pass. */
-    $and: AiContextMetadataFilter[];
-}
+export type AiContextMetadataAndFilter = MetadataAndFilter;
 /**
  * A filter combining multiple AI context metadata filters with a logical OR operation.
  * @category AI
+ * @deprecated Use {@link MetadataOrFilter} from `metadata-filter.public-types` instead.
  */
-export interface AiContextMetadataOrFilter {
-    /** An array of filters where at least one must be true for the condition to pass. */
-    $or: AiContextMetadataFilter[];
-}
+export type AiContextMetadataOrFilter = MetadataOrFilter;
 /**
  * The options for the AI knowledgebase search method.
  * @category AI
@@ -167,8 +142,9 @@ export interface AiHybridSearchWeights {
 }
 /**
  * @category AI
+ * @deprecated Use {@link MetadataFilter} from `metadata-filter.public-types` instead.
  */
-export type AiContextMetadataFilter = AiContextMetadataFieldFilter | AiContextMetadataAndFilter | AiContextMetadataOrFilter;
+export type AiContextMetadataFilter = MetadataFilter;
 /**
  * Represents an AI knowledge base's context entry with metadata and content.
  * @category AI
@@ -196,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/internal-common/src/public-types/extraction.public-types.d.ts

@@ -35,6 +35,15 @@ export interface ExtractDataFromDocumentOptions {
      * the content. Only consulted by extractors that handle text input.
      */
     textFormat?: 'auto' | 'markdown' | 'html' | 'plain';
+    /**
+     * Whether to read document-level properties (title/author/dates) from the source container and
+     * return them as `documentMetadata`. Off by default: container parsing has a real per-file cost
+     * (zip/PDF re-parse), so callers opt in only when the owning knowledge base declares metadata fields.
+     *
+     * Honored only by file-based extraction (which owns the original buffer for every format);
+     * URL-based extraction ignores it and never returns `documentMetadata`.
+     */
+    collectDocumentMetadata?: boolean;
 }
 /**
  * Request payload for extracting data from a document via URL.
@@ -108,6 +117,11 @@ export interface ExtractDataFromDocumentResponse {
      * Path to the original file in cloud storage, if applicable.
      */
     longTermStoragePath?: string;
+    /**
+     * Document-level metadata extracted from the source container (best-effort). Present only when the
+     * extractor was able to read it.
+     */
+    documentMetadata?: DocumentMetadata;
 }
 /**
  * Create PDF request type.
@@ -186,3 +200,22 @@ export interface CreatePdfResponse {
     /** The generated filename. */
     fileName?: string;
 }
+/**
+ * Document-level properties read from the source container during extraction. Every field is optional
+ * and best-effort: when a container does not expose a property (or parsing fails) the field is simply
+ * absent. Consumed by schema-driven metadata extraction as the deterministic source for matching
+ * knowledge-base `metadataFields` before falling back to LLM extraction.
+ * @category AI
+ */
+export interface DocumentMetadata {
+    /** Document title (e.g. OOXML `dc:title`, PDF `/Title`, front-matter `title`, `<title>`). */
+    docTitle?: string;
+    /** Document author (e.g. OOXML `dc:creator`, PDF `/Author`, front-matter / `<meta author>`). */
+    docAuthor?: string;
+    /** Creation timestamp, ISO 8601. */
+    docCreatedAt?: string;
+    /** Last-modified timestamp, ISO 8601. */
+    docModifiedAt?: string;
+    /** Source document type: `pdf` | `docx` | `pptx` | `xlsx` | `md` | `html` | `txt`. */
+    docType?: string;
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Generic metadata filter types used across the platform.
+ *
+ * These types define a MongoDB-style filter syntax for filtering records by metadata
+ * fields. They support field-level operators (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`,
+ * `$lte`, `$in`, `$nin`, `$exists`) and boolean combinators (`$and`, `$or`).
+ *
+ * Originally created for AI knowledge base context filtering, these types are now
+ * shared across metrics tag filtering, matchmaking, and other subsystems.
+ */
+/** Primitive metadata value. */
+export type MetadataValue = number | string | boolean | undefined;
+/** Array of metadata values (used by `$in` / `$nin`). */
+export type MetadataValueArray = MetadataValue[];
+interface MetadataEqFilter {
+    $eq: MetadataValue;
+}
+interface MetadataNeFilter {
+    $ne: MetadataValue;
+}
+interface MetadataGtFilter {
+    $gt: number;
+}
+interface MetadataGteFilter {
+    $gte: number;
+}
+interface MetadataLtFilter {
+    $lt: number;
+}
+interface MetadataLteFilter {
+    $lte: number;
+}
+interface MetadataInFilter {
+    $in: MetadataValueArray;
+}
+interface MetadataNinFilter {
+    $nin: MetadataValueArray;
+}
+interface MetadataExistsFilter {
+    $exists: boolean;
+}
+/** A single-field operator: one of `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`. */
+export type MetadataSimpleFilter = MetadataEqFilter | MetadataNeFilter | MetadataGtFilter | MetadataGteFilter | MetadataLtFilter | MetadataLteFilter | MetadataInFilter | MetadataNinFilter | MetadataExistsFilter;
+/**
+ * A filter for metadata based on field-specific conditions or direct values.
+ * @category Metadata
+ */
+export interface MetadataFieldFilter {
+    /** A record where keys are field names and values are either operator objects or direct scalar values. */
+    [field: string]: MetadataSimpleFilter | MetadataValue;
+}
+/**
+ * A filter combining multiple metadata filters with a logical AND operation.
+ * @category Metadata
+ */
+export interface MetadataAndFilter {
+    /** An array of filters that must all be true for the condition to pass. */
+    $and: MetadataFilter[];
+}
+/**
+ * A filter combining multiple metadata filters with a logical OR operation.
+ * @category Metadata
+ */
+export interface MetadataOrFilter {
+    /** An array of filters where at least one must be true for the condition to pass. */
+    $or: MetadataFilter[];
+}
+/**
+ * A composable metadata filter supporting field operators and boolean combinators.
+ *
+ * @example Simple equality
+ * ```ts
+ * { status: 'active' }
+ * ```
+ * @example Operators
+ * ```ts
+ * { age: { $gte: 18 }, role: { $in: ['admin', 'editor'] } }
+ * ```
+ * @example Boolean combinators
+ * ```ts
+ * { $or: [{ status: 'active' }, { role: { $ne: 'guest' } }] }
+ * ```
+ */
+export type MetadataFilter = MetadataFieldFilter | MetadataAndFilter | MetadataOrFilter;
+export {};

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

@@ -1,3 +1,11 @@
+import { MetadataFilter } from './metadata-filter.public-types';
+/**
+ * Tag filter for metric queries. Accepts either a simple key-value record (backward compatible)
+ * or the full {@link MetadataFilter} tree with `$eq`, `$ne`, `$in`, `$nin`, `$exists`,
+ * `$gt`, `$gte`, `$lt`, `$lte`, `$and`, `$or`.
+ * @category Metrics
+ */
+export type MetricTagFilter = Record<string, string> | MetadataFilter;
 /**
  * Name of metrics publicly provided by the system.
  * - Metrics suffixed by '_time' are 'gauge' metrics.
@@ -49,10 +57,22 @@ export interface QueryMetricsRequestCommon {
      */
     fillValue?: number | null;
     /**
-     * Tag filters.
-     * TODO: add operations to exclude tags: !=, !contains...
+     * Tag filters. Supports two formats:
+     * - Simple: `Record<string, string>` — each key-value pair is an exact equality match.
+     * - Advanced: `AiContextMetadataFilter` — the same filter syntax used by AI knowledge base
+     *   metadata, supporting `$eq`, `$ne`, `$in`, `$nin`, `$exists`, `$and`, `$or`, and
+     *   comparison operators (`$gt`, `$gte`, `$lt`, `$lte` — numeric comparisons on string tags).
+     *
+     * @example Simple format
+     * ```ts
+     * tagFilter: { aiModel: 'claude-sonnet-4-5-20250514', isError: '0' }
+     * ```
+     * @example Advanced format
+     * ```ts
+     * tagFilter: { $or: [{ aiModel: { $in: ['claude-sonnet-4-5-20250514', 'gpt-4o'] } }, { isError: { $ne: '0' } }] }
+     * ```
      */
-    tagFilter?: Record<string, string>;
+    tagFilter?: MetricTagFilter;
     /**
      * A mapping of known tag values that must be present in the response groups.
      *

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.470";
+export declare const SQUIDCLOUD_CLIENT_PACKAGE_VERSION = "1.0.472";

package/package.json

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