@squidcloud/client 1.0.369 → 1.0.371

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

@@ -546,20 +546,6 @@ export interface AnthropicChatOptions extends BaseAiChatOptions {
     /** The level of reasoning effort to apply. Defaults to no reasoning. */
     reasoningEffort?: AiReasoningEffort;
 }
-/**
- * Optional settings for an AI session, allowing partial specification of identifiers.
- * @category AI
- */
-export type AiSessionOptions = Partial<{
-    /** A unique identifier for tracing the session, if provided. */
-    traceId: string;
-    /** The ID of the client initiating the session, if specified. */
-    clientId: string;
-    /** The ID of the AI agent involved in the session, if specified. */
-    agentId: string;
-    /** The ID of the AI agent involved in starting the session, if specified. */
-    rootAgentId: string;
-}>;
 /**
  * The generic options type. When no generic is provided,
  * the type is inferred from the provided overrideModel (or falls back to BaseAiAgentChatOptions).

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

@@ -0,0 +1,59 @@
+/**
+ * Represents a unique identifier for a job.
+ */
+export type JobId = string;
+/** Represents a request to get an asynchronous job by its ID. */
+export interface GetJobRequest {
+    /** The unique identifier of the job to retrieve */
+    jobId: JobId;
+}
+/**
+ * Represents a request to get an asynchronous job by its ID.
+ */
+export interface GetJobResponse {
+    /** The job details */
+    job: AsyncJob | undefined;
+}
+/**
+ * Represents a request to subscribe to job updates.
+ * This allows clients to receive real-time updates about the job's status.
+ */
+export interface SubscribeToJobRequest {
+    /** The unique identifier of the job to subscribe to */
+    jobId: JobId;
+}
+/**
+ * Represents an asynchronous job
+ */
+export interface AsyncJob<T = any> {
+    /**
+     * The unique identifier of the job.
+     */
+    id: JobId;
+    /**
+     * The timestamp when the job was created.
+     */
+    createdAt: Date;
+    /**
+     * The timestamp when the job was last updated.
+     */
+    updatedAt: Date;
+    /**
+     * The current status of the job.
+     * Can be one of the following:
+     * - 'in_progress': The job is currently being processed.
+     * - 'completed': The job has finished successfully.
+     * - 'failed': The job has failed.
+     */
+    status: 'in_progress' | 'completed' | 'failed';
+    /**
+     * The result of the job, if available.
+     * This is of type `T` and is optional.
+     */
+    result?: T;
+    /**
+     * The error message, if the job has failed.
+     * This is optional.
+     */
+    error?: string;
+}

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

@@ -1,6 +1,7 @@
 import { AgentContextRequest, AiAgent, AiAgentContext, AiAudioCreateSpeechOptions, AiChatModelName, AiChatOptions, AiContextMetadata, AiContextMetadataFilter, AiEmbeddingsModelName, AiGenerateImageOptions, AiProviderType, AiSearchOptions, AiSearchResultChunk, AllAiAgentChatOptions, ApplicationAiSettings } from '../public-types/ai-agent.public-types';
 import { AiFunctionId } from '../public-types/backend.public-types';
 import { AiAgentId, AppId, ClientRequestId } from '../public-types/communication.public-types';
+import { JobId } from '../public-types/job.public-types';
 import { SecretKey } from '../public-types/secret.public-types';
 export type ModelDataType = {
     maxTokens: number;
@@ -12,11 +13,13 @@ export interface AiChatRequest {
     clientRequestId: ClientRequestId;
     prompt?: string;
     options?: AllAiAgentChatOptions;
+    jobId: JobId;
 }
 export interface AiAskRequest {
     agentId: AiAgentId;
     prompt?: string;
     options?: AllAiAgentChatOptions;
+    jobId: JobId;
 }
 export interface AiGenerateImageRequest {
     prompt: string;

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

@@ -1,5 +1,6 @@
 import { Observable } from 'rxjs';
 import { AgentContextRequest, AiAgent, AiAgentContext, AiChatModelName, AiConnectedAgentMetadata, AiObserveStatusOptions, AiSearchOptions, AiSearchResultChunk, AiStatusMessage, AiTranscribeAndAskResponse, GuardrailsOptions, UpsertAgentRequest } from '../../../internal-common/src/public-types/ai-agent.public-types';
+import { JobId } from '../../../internal-common/src/public-types/job.public-types';
 import { AiAskOptions, AiAskOptionsWithVoice, AiChatOptionsWithoutVoice, AskWithVoiceResponse, TranscribeAndAskWithVoiceResponse, TranscribeAndChatResponse } from './ai-agent-client.types';
 /**
  * Parameters for creating or updating an AI agent.
@@ -19,6 +20,7 @@ export declare class AiAgentReference {
     private readonly statusUpdates;
     private readonly rpcManager;
     private readonly socketManager;
+    private readonly jobClient;
     /**
      * Retrieves metadata and configuration of the AI agent.
      */
@@ -89,36 +91,76 @@ export declare class AiAgentReference {
     deleteCustomGuardrail(): Promise<void>;
     /**
      * Sends a prompt to the agent and receives streamed text responses.
+     * @param prompt The text prompt to send to the agent.
+     * @param options Optional parameters for the AI ask request.
+     * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or
+     *   `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who
+     *   knows it can look up the job’s status.
      */
-    chat<T extends AiChatModelName | undefined>(prompt: string, options?: AiChatOptionsWithoutVoice<T>): Observable<string>;
+    chat<T extends AiChatModelName | undefined>(prompt: string, options?: AiChatOptionsWithoutVoice<T>, jobId?: JobId): Observable<string>;
     /**
      * Transcribes the given file and performs a chat interaction.
+     * @param fileToTranscribe The audio file to transcribe and send to the agent.
+     * @param options Optional parameters for the AI ask request.
+     * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or
+     *   `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who
+     *   knows it can look up the job’s status.
      */
-    transcribeAndChat(fileToTranscribe: File, options?: AiChatOptionsWithoutVoice): Promise<TranscribeAndChatResponse>;
+    transcribeAndChat(fileToTranscribe: File, options?: AiChatOptionsWithoutVoice, jobId?: JobId): Promise<TranscribeAndChatResponse>;
     /**
      * Performs a semantic search using the agent's knowledge base.
      */
     search(options: AiSearchOptions): Promise<Array<AiSearchResultChunk>>;
     /**
      * Sends a prompt and receives a full string response.
+     * @param prompt The text prompt to send to the agent.
+     * @param options Optional parameters for the AI ask request.
+     * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or
+     *   `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who
+     *   knows it can look up the job’s status.
      */
-    ask<T extends AiChatModelName | undefined = undefined>(prompt: string, options?: AiAskOptions<T>): Promise<string>;
+    ask<T extends AiChatModelName | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<string>;
+    /**
+     * Sends a prompt and not wait for the result - the result can be tracked using the job ID
+     * (`squid.jobs().awaitJob(jobId)` or `squid.jobs().getJob(jobId)).
+     * @param prompt The text prompt to send to the agent.
+     * @param jobId A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or
+     *   `squid.jobs().getJob(jobId)`
+     to track progress. Make sure each job ID is both unique and kept private—anyone who knows it can look up the job’s status.
+     * @param options Optional parameters for the AI ask request.
+     */
+    askAsync<T extends AiChatModelName | undefined = undefined>(prompt: string, jobId: JobId, options?: AiAskOptions<T>): Promise<void>;
     /**
      * Observes live status messages from the agent.
      */
     observeStatusUpdates(options?: AiObserveStatusOptions): Observable<AiStatusMessage>;
     /**
      * Transcribes audio and sends it to the agent for response.
+     * @param fileToTranscribe The audio file to transcribe and send to the agent.
+     * @param options Optional parameters for the AI ask request.
+     * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or
+     *   `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who
+     *   knows it can look up the job’s status.
      */
-    transcribeAndAsk<T extends AiChatModelName | undefined>(fileToTranscribe: File, options?: AiAskOptions<T>): Promise<AiTranscribeAndAskResponse>;
+    transcribeAndAsk<T extends AiChatModelName | undefined>(fileToTranscribe: File, options?: AiAskOptions<T>, jobId?: JobId): Promise<AiTranscribeAndAskResponse>;
     /**
      * Transcribes audio and gets both text and voice response from the agent.
+     * @param fileToTranscribe The audio file to transcribe and send to the agent.
+     * @param options Optional parameters for the AI ask request.
+     * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or
+     *   `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who
+     *   knows it can look up the job’s status.
      */
-    transcribeAndAskWithVoiceResponse<T extends AiChatModelName | undefined>(fileToTranscribe: File, options?: AiAskOptionsWithVoice<T>): Promise<TranscribeAndAskWithVoiceResponse>;
+    transcribeAndAskWithVoiceResponse<T extends AiChatModelName | undefined>(fileToTranscribe: File, options?: AiAskOptionsWithVoice<T>, jobId?: JobId): Promise<TranscribeAndAskWithVoiceResponse>;
     /**
      * Sends a prompt and gets both text and voice response from the agent.
+     * @param prompt The text prompt to send to the agent.
+     * @param options Optional parameters for the AI ask request.
+     * @param jobId (Optional) A unique identifier for this request. Use it with `squid.jobs().awaitJob(jobId)` or
+     *   `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who
+     *   knows it can look up the job’s status.
      */
-    askWithVoiceResponse<T extends AiChatModelName | undefined>(prompt: string, options?: AiAskOptionsWithVoice<T>): Promise<AskWithVoiceResponse>;
+    askWithVoiceResponse<T extends AiChatModelName | undefined>(prompt: string, options?: AiAskOptionsWithVoice<T>, jobId?: JobId): Promise<AskWithVoiceResponse>;
     private askInternal;
     private createStatusSubject;
     private chatInternal;

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

@@ -9,6 +9,7 @@ import { AiAgentReference } from './ai-agent-client-reference';
 export declare class AiAgentClient {
     private readonly rpcManager;
     private readonly socketManager;
+    private readonly jobClient;
     private readonly ongoingChatSequences;
     private readonly statusUpdates;
     /**

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

@@ -14,6 +14,7 @@ import { AiAgent, AiAgentId, AiProviderType, ApplicationAiSettings, IntegrationI
 export declare class AiClient {
     private readonly socketManager;
     private readonly rpcManager;
+    private readonly jobClient;
     private readonly aiAssistantClient;
     private aiAgentClient?;
     /**
@@ -97,4 +98,5 @@ export declare class AiClient {
      * Returns the updated state of the AI application settings.
      */
     setAiProviderApiKeySecret(providerType: AiProviderType, secretKey: SecretKey | undefined): Promise<ApplicationAiSettings>;
+    private getAiAgentClient;
 }

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

@@ -27,6 +27,7 @@ export * from './execute-function-options';
 export * from './extraction-client';
 export * from './file-utils';
 export * from './integration-client';
+export * from './job-client';
 export * from './mutation/mutation-sender';
 export * from './native-query-manager';
 export * from './observability-client';

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

@@ -0,0 +1,31 @@
+import { AsyncJob, JobId } from '../../internal-common/src/public-types/job.public-types';
+/**
+ * Handles job subscriptions and notifications.
+ *
+ * **Important:** Each `jobId` must be globally unique and kept private.
+ * Anyone who knows a job’s ID can query its status or result.
+ */
+export declare class JobClient {
+    private readonly socketManager;
+    private readonly rpcManager;
+    private isListening;
+    private readonly listeners;
+    /**
+     * Retrieves the current status (and, if completed, the result) of a job.
+     *
+     * @param jobId A unique, private identifier for the job.
+     *              Do **not** reuse a `jobId` across clients—possessing the ID
+     *              allows anyone to inspect the job’s state.
+     */
+    getJob<T = any>(jobId: JobId): Promise<AsyncJob<T> | undefined>;
+    /**
+     * Waits until the specified job finishes, then resolves with its result or
+     * throws if the job fails.
+     *
+     * @param jobId A unique, private identifier for the job.
+     *              Do **not** reuse a `jobId` across clients—possessing the ID
+     *              allows anyone to inspect the job’s state.
+     */
+    awaitJob<T = any>(jobId: JobId): Promise<T>;
+    private maybeListenToJobs;
+}

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

@@ -12,6 +12,7 @@ export * from '../../internal-common/src/public-types/document.public-types';
 export * from '../../internal-common/src/public-types/extraction.public-types';
 export * from '../../internal-common/src/public-types/http-status.public-types';
 export * from '../../internal-common/src/public-types/integration.public-types';
+export * from '../../internal-common/src/public-types/job.public-types';
 export * from '../../internal-common/src/public-types/metric.public-types';
 export * from '../../internal-common/src/public-types/openapi.public-types';
 export * from '../../internal-common/src/public-types/query.public-types';

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

@@ -6,6 +6,7 @@ import { ConnectionDetails } from './connection-details';
 import { DistributedLock } from './distributed-lock.manager';
 import { ExecuteFunctionOptions } from './execute-function-options';
 import { ExtractionClient } from './extraction-client';
+import { JobClient } from './job-client';
 import { ObservabilityClient } from './observability-client';
 import { PersonalStorageClient } from './personal-storage-client';
 import { ApiKey, AppId, CollectionName, DocumentData, EnvironmentId, IntegrationId, SquidDeveloperId, SquidRegion } from './public-types';
@@ -108,6 +109,7 @@ export declare class Squid {
     private readonly querySender;
     private static readonly squidInstancesMap;
     private readonly aiClient;
+    private readonly jobClient;
     private readonly apiClient;
     private readonly adminClient;
     private readonly webClient;
@@ -226,10 +228,12 @@ export declare class Squid {
     executeNativeElasticQuery<T = any>(integrationId: IntegrationId, index: string, body: Record<string, any>, endpoint?: string, method?: 'GET' | 'POST'): Promise<Array<T>>;
     /**
      * Returns a set of AI specific clients.
-     *
-     * @returns A set of AI specific clients.
      */
     ai(): AiClient;
+    /**
+     * Returns a set of functionality for interacting with jobs.
+     */
+    job(): JobClient;
     /**
      * Returns a set of functionality for interacting with API integrations.
      */

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

package/package.json

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