@squidcloud/client 1.0.493 → 1.0.495

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

@@ -781,6 +781,19 @@ export type AiChatOptions<T extends AiChatModelSelection | undefined = undefined
 export type AllAiAgentChatOptions = {
     [K in keyof BaseAiChatOptions | keyof GeminiChatOptions | keyof GrokChatOptions | keyof OpenAiChatOptions | keyof AnthropicChatOptions]?: (K extends keyof BaseAiChatOptions ? BaseAiChatOptions[K] : never) | (K extends keyof GeminiChatOptions ? GeminiChatOptions[K] : never) | (K extends keyof GrokChatOptions ? GrokChatOptions[K] : never) | (K extends keyof OpenAiChatOptions ? OpenAiChatOptions[K] : never) | (K extends keyof AnthropicChatOptions ? AnthropicChatOptions[K] : never);
 };
+/**
+ * Credentials a caller sends with one chat request. The client sends them in the `x-squid-integration-access-tokens`
+ * request header rather than with the options, so they reach only the tools that run with them and are never stored
+ * with the agent.
+ * @category AI
+ */
+export interface AiChatRequestCredentials {
+    /**
+     * Access tokens keyed by integration ID. The integration's tools run with its token for this request when the
+     * integration type supports it; other types ignore it.
+     */
+    integrationAccessTokens?: Record<IntegrationId, string>;
+}
 /**
  * Configuration for exposing an AI agent as an MCP server at `/mcp/<agentId>`.
  * @category AI

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

@@ -1871,11 +1871,18 @@ export interface BulkIngestionFileStatus {
      * bytes exceed what the extraction provider accepts) and `'UNSUPPORTED_FILE_TYPE'`.
      * `'DUPLICATE_CONTENT'` is a skip rather than a failure: the KB already holds this content.
      * `'EXTRACTION_TIMED_OUT'` stays retryable — the deadline is contended, so a borderline document can
-     * cross it under load. `'JOB_FULL'`: the job's request ceiling had no room left for this file, so re-submit it
-     * in a fresh job; a file that alone exceeds the ceiling fails this way in every job. Additive; absent for
-     * ordinary failures.
+     * cross it under load. So do `'SOURCE_UNREACHABLE'` (the provider could not fetch the source, which a
+     * fresh link can fix) and `'PROVIDER_ACCESS_DENIED'` (the provider refused the credential or its quota is
+     * spent, a fault of the environment). `'JOB_FULL'`: the job's request ceiling had no room left for this
+     * file, so re-submit it in a fresh job; a file that alone exceeds the ceiling fails this way in every job.
+     * Additive; absent for ordinary failures.
      */
-    errorCode?: 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'JOB_FULL' | 'NO_EMBEDDABLE_CONTENT' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'UNSUPPORTED_FILE_TYPE';
+    errorCode?: 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'JOB_FULL' | 'NO_EMBEDDABLE_CONTENT' | 'PROVIDER_ACCESS_DENIED' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'SOURCE_UNREACHABLE' | 'UNSUPPORTED_FILE_TYPE';
+    /**
+     * Present only on a failed file an extraction provider answered: a stable fingerprint of that answer
+     * (provider, HTTP status and provider code), so a caller can tell the same failure repeating from a new one.
+     */
+    errorSignature?: string;
     /**
      * Present only on a failed file: the same bytes fail the same way, so a caller must park the file
      * instead of re-submitting it. Absence means retryable.

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

@@ -39,6 +39,18 @@ export interface AiQueryOptions {
     /** Optional AI validation of generated queries. Can be used independently or with generateQueriesOnly. */
     validateWithAiOptions?: AiQueryValidateWithAiOptions;
 }
+/**
+ * Options of a single AI query call: the query options plus a credential the client sends as a request header.
+ * @category AI
+ */
+export interface AiQueryRequestOptions extends AiQueryOptions {
+    /**
+     * Access token the generated queries run with in place of the integration's stored secret, for integration
+     * types that support it. Other types ignore it. Sent in the `x-squid-integration-access-tokens` request header
+     * rather than with the options, so it is never stored.
+     */
+    accessToken?: string;
+}
 /**
  * Request to execute an AI query using a specific integration.
  * Supports additional query execution options.

package/dist/internal-common/src/types/headers.types.d.ts

@@ -25,6 +25,12 @@ export declare const SquidHeaders: {
     readonly CLIENT_VERSION: "x-squid-client-version";
     /** Originating IP address of the request. */
     readonly SOURCE_IP: "x-squid-source-ip";
+    /**
+     * Access tokens the caller supplies for the request's integrations, as a JSON object keyed by
+     * integration ID. An integration type that runs with one takes it in place of its stored secret.
+     * The header stays in the cores and never reaches tenant code.
+     */
+    readonly INTEGRATION_ACCESS_TOKENS: "x-squid-integration-access-tokens";
     /**
      * Response-only: IP of the tenant pod that served the request, i.e. the address to reach it at
      * again. Core records it to route subsequent affinity-keyed calls to the same pod. Absent when the

package/dist/internal-common/src/types/observability.types.d.ts

@@ -6,6 +6,7 @@ export interface ObservableNameMetrics {
 }
 export declare const ObservableNames: {
     readonly nativeQuery: ObservableNameMetrics;
+    readonly registerQuery: ObservableNameMetrics;
     readonly query: ObservableNameMetrics;
     readonly mutate: ObservableNameMetrics;
     readonly functionExecution: ObservableNameMetrics;

package/dist/internal-common/src/utils/http-utils.d.ts

@@ -0,0 +1,15 @@
+import { ObjectAssertion } from 'assertic';
+import { HttpStatusCode } from '../public-types/http-status.public-types';
+export type HttpQueryParams = Record<string, string | number | boolean>;
+/**
+ * Asserts that a value is truthy. Throws a {@link ValidationError} with the given HTTP status code if it is not.
+ * Narrows the type of `value` to exclude `null`, `undefined`, `false`, `0`, and `''`.
+ */
+export declare function assertHttp<T>(value: T, message: string, status: HttpStatusCode): asserts value is NonNullable<T> & (T extends false | 0 | '' ? never : T);
+/**
+ * Asserts that an object matches the given ObjectAssertion.
+ * Re-throws any non-ValidationError as BAD_REQUEST.
+ */
+export declare function assertHttpInput<T>(value: T, assertion: ObjectAssertion<T>): asserts value is T;
+/** Builds a query string from the record of key-value pairs. */
+export declare function buildHttpQueryString(queryParams: HttpQueryParams): string;

package/dist/internal-common/src/utils/integration-access-tokens.d.ts

@@ -0,0 +1,15 @@
+import { AiChatRequestCredentials } from '../public-types/ai-agent.public-types';
+import { IntegrationId } from '../public-types/communication.public-types';
+/** Access tokens a caller supplies for one request, keyed by integration ID. */
+export type IntegrationAccessTokens = Record<IntegrationId, string>;
+/** Serializes [tokens] into the value of the {@link SquidHeaders.INTEGRATION_ACCESS_TOKENS} header. */
+export declare function serializeIntegrationAccessTokens(tokens: IntegrationAccessTokens): string;
+/** Parses the {@link SquidHeaders.INTEGRATION_ACCESS_TOKENS} header value; a malformed value is a bad request. */
+export declare function parseIntegrationAccessTokens(headerValue: string): IntegrationAccessTokens;
+/** Builds the request headers that carry [tokens]; empty when there is nothing to send. */
+export declare function toIntegrationAccessTokenHeaders(tokens: IntegrationAccessTokens | undefined): Record<string, string>;
+/** Splits the tokens off the call [options]: the headers that carry them, and the options the request body takes. */
+export declare function splitIntegrationAccessTokens<T extends AiChatRequestCredentials>(options: T | undefined): {
+    headers: Record<string, string>;
+    options: Omit<T, 'integrationAccessTokens'> | undefined;
+};

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

@@ -262,7 +262,7 @@ export declare class AiAgentReference {
      */
     private withMetricAnnotations;
     /**
-     * Calls rpcManager post but with the agent api key if one was given during construction
+     * Calls rpcManager post with [headers], adding the agent api key if one was given during construction
      */
     private post;
 }

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

@@ -1,5 +1,5 @@
 import { Observable } from 'rxjs';
-import { AiAnnotation, AiChatModelSelection, AiChatOptions } from '../../../internal-common/src/public-types/ai-agent.public-types';
+import { AiAnnotation, AiChatModelSelection, AiChatOptions, AiChatRequestCredentials } from '../../../internal-common/src/public-types/ai-agent.public-types';
 /**
  * Response format for transcribing audio and generating a chat response.
  * Contains the transcribed text and a stream of AI-generated responses.
@@ -51,18 +51,18 @@ export interface AskWithVoiceResponse {
  */
 export type AiChatOptionsWithoutVoice<T extends AiChatModelSelection | undefined = undefined> = Omit<AiChatOptions<T>, 'voiceOptions'> & {
     model?: T;
-};
+} & AiChatRequestCredentials;
 /**
  * Options for AI-generated responses that exclude voice-specific settings and smooth typing behavior.
  * @category AI
  */
 export type AiAskOptions<T extends AiChatModelSelection | undefined = undefined> = Omit<AiChatOptions<T>, 'voiceOptions' | 'smoothTyping'> & {
     model?: T;
-};
+} & AiChatRequestCredentials;
 /**
  * Options for AI-generated responses that include voice-specific settings but excludes smooth typing.
  * @category AI
  */
 export type AiAskOptionsWithVoice<T extends AiChatModelSelection | undefined = undefined> = Omit<AiChatOptions<T>, 'smoothTyping'> & {
     model?: T;
-};
+} & AiChatRequestCredentials;

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, AiSpreadsheetQueryOptions, ExecuteAiApiResponse, ExecuteAiSpreadsheetQueryResponse } from '../../internal-common/src/public-types/ai-query.public-types';
+import { AiQueryRequestOptions, 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';
@@ -102,7 +102,8 @@ export declare class AiClient {
      * @param prompt        The text prompt to send to the AI. This should be formulated in a way that the AI can
      *                      understand and respond to, taking into account the nature of the task or the information
      *                      sought.
-     * @param options       Additional options to customize the query execution.
+     * @param options       Additional options to customize the query execution. An `accessToken` is sent as a request
+     *                      header rather than with the options.
      * @param abortSignal   Optional signal used to abort the underlying request. When the signal aborts, the in-flight
      *                      HTTP request is cancelled and its promise rejects, allowing callers to bound a single call
      *                      without leaking the request.
@@ -121,7 +122,7 @@ export declare class AiClient {
      * For more details on the usage and capabilities of the AI Assistant, refer to the documentation provided at
      * {@link https://docs.squid.cloud/docs/ai}.
      */
-    executeAiQuery(integrationId: IntegrationId, prompt: string, options?: AiQueryOptions, abortSignal?: AbortSignal): Promise<AiQueryResponse>;
+    executeAiQuery(integrationId: IntegrationId, prompt: string, options?: AiQueryRequestOptions, abortSignal?: AbortSignal): Promise<AiQueryResponse>;
     /**
      * Executes an AI-powered API call using a specific integration.
      * The AI will select appropriate endpoints, generate request bodies,

package/dist/typescript-client/src/document-reference.d.ts

@@ -18,6 +18,7 @@ export declare class DocumentReference<T extends DocumentData = any> {
     private readonly dataManager;
     private readonly queryBuilderFactory;
     private readonly projectFields?;
+    private readonly identityReference?;
     /** A string that uniquely identifies this document reference. */
     refId: string;
     /**

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

package/package.json

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