@squidcloud/client 1.0.478 → 1.0.479

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

@@ -837,6 +837,14 @@ export interface UpsertContextStatusSuccess extends BaseUpsertContextStatus {
     /** Whether the context upsert was successful or got an error. */
     status: 'success';
 }
+/**
+ * Machine-readable code identifying a specific upsert failure reason.
+ *
+ * `DUPLICATE_CONTENT` means the request omitted a contextId and its content is
+ * byte-identical to an existing context in the same knowledge base.
+ * @category AI
+ */
+export type UpsertContextErrorCode = 'DUPLICATE_CONTENT';
 /**
  * Status of an individual context item after it failed to upsert.
  *
@@ -848,6 +856,8 @@ export interface UpsertContextStatusError extends BaseUpsertContextStatus {
     status: 'error';
     /** Reason the upsert failed. */
     errorMessage: string;
+    /** Machine-readable code for the failure, when one applies. */
+    errorCode?: UpsertContextErrorCode;
 }
 /**
  * Status of an individual context item after attempting to upsert it.
@@ -1020,6 +1030,16 @@ export type AiSessionContext = {
     agentId: string;
     /** The ID of the job associated with the session. */
     jobId: JobId;
+    /**
+     * ID of the status update that triggered this session (e.g. the agent's "Calling AI Function"
+     * event). Status updates emitted on behalf of this session nest under it in the status feed.
+     */
+    parentStatusUpdateId?: string;
+    /**
+     * Whether the invoking agent has audit logging enabled. Sub-agents working on behalf of this
+     * session gate their own audit-log writes on it, keeping one job's audit trail consistent.
+     */
+    auditLog?: boolean;
     /**
      * The chat timeout (in milliseconds) the root chat request explicitly set. Present only when
      * the root request passed `timeoutMs`. Nested AI operations (e.g. AI-query stages spawned by a

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

@@ -211,6 +211,11 @@ export interface AiKnowledgeBaseContext {
      * user-supplied values are preserved; consumers can also use this to caveat extracted values.
      */
     autoExtractedMetadataFields?: string[];
+    /**
+     * SHA-256 (hex) of the source bytes (file) or UTF-8 text this context was ingested from. Powers
+     * content-level dedup on upsert. Absent on legacy contexts ingested before hashing was introduced.
+     */
+    contentHash?: string;
     /** Original request configuration for how the context content was processed. */
     requestConfig?: AgentContextRequest;
 }
@@ -228,7 +233,7 @@ export type AiKnowledgeBaseContextRequest = AiKnowledgeBaseTextContextRequest |
  */
 export interface BaseAiKnowledgeBaseContextRequest {
     /** The unique identifier of the context item. */
-    contextId: string;
+    contextId?: string;
     /** The type of the context content. */
     type: AiKnowledgeBaseContextType;
     /** Optional metadata associated with the context item. */
@@ -262,8 +267,13 @@ export type AiKnowledgeBaseTextFormat = 'auto' | 'markdown' | 'html' | 'plain';
  * @category AI
  */
 export interface AiKnowledgeBaseTextContextRequest extends BaseAiKnowledgeBaseContextRequest {
-    /** The id of the context */
-    contextId: AiContextId;
+    /**
+     * The id of the context. Optional: when omitted, the server generates one and rejects the upload if
+     * another context in the knowledge base already holds identical content (content-level dedup). Provide
+     * an explicit id to address a specific context — that overwrites it unconditionally and allows duplicate
+     * content across different ids.
+     */
+    contextId?: AiContextId;
     /** Specifies the context type as 'text'. */
     type: 'text';
     /** A title for the text context. */
@@ -298,8 +308,13 @@ export interface AiKnowledgeBaseTextContextRequest extends BaseAiKnowledgeBaseCo
  * @category AI
  */
 export interface AiKnowledgeBaseFileContextRequest extends BaseAiKnowledgeBaseContextRequest {
-    /** The id of the context */
-    contextId: AiContextId;
+    /**
+     * The id of the context. Optional: when omitted, the server generates one and rejects the upload if
+     * another context in the knowledge base already holds identical content (content-level dedup). Provide
+     * an explicit id to address a specific context — that overwrites it unconditionally and allows duplicate
+     * content across different ids.
+     */
+    contextId?: AiContextId;
     /** Specifies the context type as 'file'. */
     type: 'file';
     /** Whether to extract images from the file; defaults to false. */
@@ -410,6 +425,16 @@ export interface UpsertKnowledgeBaseContextResponse {
 export interface UpsertKnowledgeBaseContextsResponse {
     /** List of the upsert status of each item sent in the request. */
     failures: Array<UpsertContextStatusError>;
+    /**
+     * The context id of every request in the batch, positionally aligned with the `contextRequests` array
+     * that was sent — `contextIds[i]` is the id of the i-th request. Each entry is the caller-supplied id,
+     * or the id the server generated when the request omitted one, and is present regardless of whether that
+     * request succeeded or failed. Lets a caller that upserts without a contextId learn the assigned id.
+     *
+     * Optional because a newer client talking to an older core (which predates this field) receives it as
+     * `undefined` at runtime — callers must handle its absence rather than trust it is always populated.
+     */
+    contextIds?: Array<AiContextId>;
 }
 /**
  * Request structure for searching an AiKnowledgeBase

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

@@ -1,4 +1,5 @@
 import { AiAgentMemoryOptions, AiChatOptions, AiFileUrl, AiSessionContext } from './ai-agent.public-types';
+import { AiChatModelName } from './ai-common.public-types';
 import { ApiOptions } from './api-client.public-types';
 import { AiAgentId, IntegrationId } from './communication.public-types';
 import { PartialBy } from './typescript.public-types';
@@ -201,3 +202,47 @@ export interface ExecuteAiApiResponse {
     /** Indicates whether the API request execution was successful. */
     success: boolean;
 }
+/**
+ * Options for executing an AI-powered query over spreadsheet files.
+ * @category AI
+ */
+export interface AiSpreadsheetQueryOptions {
+    /**
+     * Extra instructions honored when composing the answer (e.g. formatting rules or domain
+     * conventions of the calling agent).
+     */
+    instructions?: string;
+    /** Overrides the model used to answer the query. */
+    model?: AiChatModelName;
+}
+/**
+ * Request for executing an AI-powered query over spreadsheet files.
+ * @category AI
+ */
+export interface ExecuteAiSpreadsheetQueryRequest {
+    /** Natural language question to answer using the spreadsheet data. */
+    prompt: string;
+    /** The spreadsheet files to query. */
+    files: Array<AiFileUrl>;
+    /** Optional query options. */
+    options?: AiSpreadsheetQueryOptions;
+    /** Optional session context for status updates and tracing. */
+    sessionContext?: AiSessionContext;
+}
+/**
+ * Response from executing an AI-powered query over spreadsheet files.
+ * @category AI
+ */
+export interface ExecuteAiSpreadsheetQueryResponse {
+    /** AI-generated answer computed from the spreadsheet data. */
+    answer: string;
+    /** Indicates whether the query execution was successful. */
+    success: boolean;
+    /**
+     * All Python code executed to produce the answer, in execution order. Each step ran as its own
+     * sandbox script; multiple steps are joined with `# --- Step N ---` separators.
+     */
+    executedCode?: string;
+    /** Files produced while answering (e.g. charts or exports emitted by the executed code). */
+    files?: Array<AiFileUrl>;
+}

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

@@ -105,6 +105,32 @@ export interface ExtractDataFromDocumentPage {
      */
     images: Array<ExtractDataFromDocumentImage>;
 }
+/**
+ * Structural information about one sheet of a spreadsheet file.
+ */
+export interface SpreadsheetSheetInfo {
+    /**
+     * The sheet name.
+     */
+    name: string;
+    /**
+     * Number of data rows in the sheet (excluding the header row).
+     */
+    rowCount: number;
+    /**
+     * Number of columns in the sheet.
+     */
+    columnCount: number;
+}
+/**
+ * Structural information about a parseable spreadsheet document.
+ */
+export interface SpreadsheetDocumentInfo {
+    /**
+     * The sheets of the spreadsheet, in workbook order.
+     */
+    sheets: Array<SpreadsheetSheetInfo>;
+}
 /**
  * The full result of extracting data from a document, including all pages and any extracted images.
  */
@@ -122,6 +148,11 @@ export interface ExtractDataFromDocumentResponse {
      * extractor was able to read it.
      */
     documentMetadata?: DocumentMetadata;
+    /**
+     * Structural information about the sheets when the document is a parseable spreadsheet
+     * (best-effort). Presence marks the document for the spreadsheet summary-embedding lane.
+     */
+    spreadsheet?: SpreadsheetDocumentInfo;
 }
 /**
  * Create PDF request type.

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

@@ -1,6 +1,6 @@
 import { Observable } from 'rxjs';
 import { AiFunctionMetadata } from '../../internal-common/src/public-types/ai-function.public-types';
-import { AiQueryOptions, AiQueryResponse, ExecuteAiApiResponse } from '../../internal-common/src/public-types/ai-query.public-types';
+import { AiQueryOptions, AiQueryResponse, AiSpreadsheetQueryOptions, ExecuteAiApiResponse, ExecuteAiSpreadsheetQueryResponse } from '../../internal-common/src/public-types/ai-query.public-types';
 import { AiAgentClientOptions } from './agent/ai-agent-client';
 import { AiAgentReference } from './agent/ai-agent-client-reference';
 import { AiAudioClient } from './ai-audio-client';
@@ -8,7 +8,7 @@ import { AiFilesClient } from './ai-files-client';
 import { AiImageClient } from './ai-image-client';
 import { AiKnowledgeBaseReference } from './ai-knowledge-base/ai-knowledge-base-client-reference';
 import { AiMatchMakingClient } from './ai-matchmaking-client';
-import { AiAgent, AiAgentApiIntegrationOptions, AiAgentId, AiFileProviderType, AiKnowledgeBase, AiKnowledgeBaseId, AiProviderType, AiSessionContext, AiStatusMessage, ApplicationAiSettings, IntegrationId, JobId, ListChatModelsRequest, ModelIdSpec, SecretKey } from './public-types';
+import { AiAgent, AiAgentApiIntegrationOptions, AiAgentId, AiFileProviderType, AiFileUrl, AiKnowledgeBase, AiKnowledgeBaseId, AiProviderType, AiSessionContext, AiStatusMessage, ApplicationAiSettings, IntegrationId, JobId, ListChatModelsRequest, ModelIdSpec, SecretKey } from './public-types';
 /**
  * AiClient class serves as a facade for interacting with different AI services.
  * It provides simplified access to AI chatbot and assistant functionalities
@@ -121,6 +121,17 @@ export declare class AiClient {
      * @returns Promise resolving to the API call result with answer and execution details
      */
     executeAiApiCall(integrationId: IntegrationId, prompt: string, options?: AiAgentApiIntegrationOptions, sessionContext?: AiSessionContext): Promise<ExecuteAiApiResponse>;
+    /**
+     * Executes an AI-powered query over spreadsheet files. The AI lists sheets and runs Python code
+     * against the actual files in a sandbox to compute the answer.
+     *
+     * @param prompt - Natural language question to answer using the spreadsheet data
+     * @param files - The spreadsheet files to query
+     * @param options - Optional query options (extra instructions, model override)
+     * @param sessionContext - Optional session context for status updates and tracing
+     * @returns Promise resolving to the computed answer and execution details
+     */
+    executeAiSpreadsheetQuery(prompt: string, files: Array<AiFileUrl>, options?: AiSpreadsheetQueryOptions, sessionContext?: AiSessionContext): Promise<ExecuteAiSpreadsheetQueryResponse>;
     /**
      * Returns name of the secret that stores API key for the given AI provider type.
      * This API key is used for all requests to the AI provider done from the application.

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

@@ -66,7 +66,9 @@ export declare class AiKnowledgeBaseReference {
      */
     upsertContext(contextRequest: AiKnowledgeBaseContextRequest, file?: File): Promise<UpsertKnowledgeBaseContextResponse>;
     /**
-     * Adds or updates multiple contexts.
+     * Adds or updates multiple contexts. A context request may omit its `contextId`; when it does, the server
+     * generates one and rejects the request if identical content already exists in the knowledge base
+     * (content-level dedup). Requests that carry an explicit `contextId` overwrite that context unconditionally.
      */
     upsertContexts(contextRequests: Array<AiKnowledgeBaseContextRequest>, files?: Array<File>): Promise<UpsertKnowledgeBaseContextsResponse>;
     /**

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

package/package.json

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