@squidcloud/client 1.0.498 → 1.0.500

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

@@ -0,0 +1,93 @@
+/** Splits a field path into the segments `getInPath` walks: a dot or a bracket separates them. */
+export declare const SPLIT_REGEX_FOR_GET_IN_PATH: RegExp;
+/** Returns a value by the `path`. Works with array indexes, like a.b[0]. */
+export declare function getInPath(obj: unknown, path: string): any;
+export declare function isDateObject(value: unknown): value is Date;
+/** Sets a value by path . Does not support array indexes. */
+export declare function setInPath(obj: object, path: string, value: unknown, delimiter?: string): void;
+export declare function deleteInPath(obj: object, path: string, delimiter?: string): void;
+export declare function replaceKeyInMap<K, T>(map: Map<K, T | undefined>, a: K, b: K): void;
+export declare function replaceKeyInRecord<K extends keyof any, T>(record: Record<K, T>, a: K, b: K): void;
+export declare function isNil(obj: unknown): obj is null | undefined;
+export declare function isEqual(a: unknown, b: unknown): boolean;
+export declare function isEmpty(a: unknown): boolean;
+export declare function omit<T extends object, K extends PropertyKey[]>(object: T | null | undefined, ...fieldsToRemove: K): Pick<T, Exclude<keyof T, K[number]>>;
+export type CloneCustomizer = (value: unknown) => unknown | undefined;
+/**
+ * Creates a deep copy of the specified object, including all nested objects and specifically handling Date, Map, and
+ * Set fields.
+ *
+ * The customizer function can modify the cloning process for the object and its fields. If the customizer
+ * returns 'undefined' for any input, the function falls back to the standard cloning logic.
+ *
+ * The cloning process is recursive, ensuring deep cloning of all objects.
+ *
+ * Note: This function does not support cloning objects with circular dependencies and will throw a system stack
+ * overflow error if encountered.
+ */
+export declare function cloneDeep<R = unknown>(value: R, customizer?: CloneCustomizer): R;
+/** Creates a shallow clone of the object. */
+export declare function cloneShallow<T>(value: T): T;
+export declare function deepMerge<T extends object, U extends object>(target: T, source: U): T & U;
+/** Returns true if the `value` is a defined object and is not an array. */
+export declare function isPlainObject(value: unknown): value is object;
+/**
+ * Returns true if the `value` is an object that JSON can hold as it is: a plain object whose values are JSON at any
+ * depth, with no `__proto__` key. A `Date` or another class instance is not one.
+ */
+export declare function isJsonObject(value: unknown): value is Record<string, unknown>;
+/** Compares 2 values. 'null' and 'undefined' values are considered equal and are less than any other values. */
+export declare function compareValues(v1: unknown, v2: unknown): number;
+/** Returns a new object with all top-level object fields re-mapped using `valueMapperFn`. */
+export declare function mapValues<ResultType extends object = Record<string, unknown>, InputType extends Record<string, unknown> = Record<string, unknown>>(obj: InputType, valueMapperFn: (value: any, key: keyof InputType, obj: InputType) => unknown): ResultType;
+/** Groups elements of the array by key. See _.groupBy for details. */
+export declare function groupBy<T, K extends PropertyKey>(array: T[], getKey: (item: T) => K): Record<K, T[]>;
+/**
+ * Picks selected fields from the object and returns a new object with the fields selected.
+ * The selected fields are assigned by reference (there is no cloning).
+ */
+export declare function pick<T extends object, K extends keyof T>(obj: T, keys: ReadonlyArray<K>): Pick<T, K>;
+/** Inverts the record: swaps keys and values. */
+export declare function invert<K extends string | number, V extends string | number>(record: Record<K, V>): Record<V, K>;
+/**
+ * Creates an array of numbers (positive and/or negative) progressing from start up to, but not including, end.
+ * If end is less than start a zero-length range is created unless a negative step is specified.
+ *
+ * Same as lodash range but with an additional parameter: `maximumNumberOfItems`.
+ */
+export declare function range(start: number, end: number, step: number, maximumNumberOfItems?: number): number[];
+/** Returns count of top level properties in object. */
+export declare function countObjectKeys(obj: object | undefined | null): number;
+/** Returns object entries sorted by name. */
+export declare function getSortedEntries<T>(record: Record<string, T>): Array<[string, T]>;
+/** Removes top level fields which are empty objects. May be used for value formatting. */
+export declare function removeEmptyTopLevelRecords<T extends object>(record: T): Partial<T>;
+export declare function removeUndefinedValues<V>(tags: Record<string, V | undefined>): Record<string, V>;
+export declare function extractKey(line: string | undefined): string | null;
+/** Represents a line in a diff output */
+export interface DiffLine {
+    lineNumber: number;
+    text: string;
+    type: 'unchanged' | 'added' | 'removed' | 'changed';
+}
+/** Result of computing a line-by-line diff between two objects */
+export interface DiffResult {
+    leftLines: Array<DiffLine>;
+    rightLines: Array<DiffLine>;
+    hasChanges: boolean;
+}
+/**
+ * Computes a line-by-line diff between two objects.
+ * Objects are serialized to JSON with sorted keys for consistent comparison.
+ * @param before The previous/left object (can be undefined for new objects)
+ * @param after The current/right object
+ * @returns DiffResult with left and right lines and whether there are changes
+ */
+export declare function computeObjectDiff(before: unknown, after: unknown): DiffResult;
+/**
+ * Formats an object as diff lines (all unchanged).
+ * Useful for displaying a single object without comparison.
+ * @param obj The object to format
+ * @returns Array of DiffLine with all lines marked as unchanged
+ */
+export declare function formatObjectAsLines(obj: unknown): Array<DiffLine>;

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

@@ -0,0 +1,30 @@
+export declare function sortKeys(json: unknown): any;
+export declare function normalizeJsonAsString(json: unknown): string;
+export declare function serializeObj(obj: unknown): string;
+/**
+ * A `JSON.stringify` replacer writing a `Date` as `{ $date }`, the form {@link deserializeObj} reads back,
+ * for callers that keep every other value's own `toJSON`. The date is read off the holder, since a
+ * replacer is handed the `toJSON` text of a date; an invalid date keeps that text, `null`.
+ */
+export declare function writeDateAsBson(this: Record<string, unknown>, key: string, value: unknown): unknown;
+export declare function deserializeObj<T = any>(str: string): T;
+/**
+ * Deserializes a multipart request payload when present.
+ * NestJS does not pull the body out of a multipart request, and leaves the JSON payload in its `body` form field;
+ * plain JSON requests carry the payload as-is.
+ */
+export declare function deserializeMultipartBody<T>(request: T): T;
+export declare function encodeValueForMapping(value: unknown): string;
+export declare function decodeValueForMapping(encodedString: string): any;
+/**
+ * Compares 2 objects by their normalized JSON value.
+ * This function should not be used with objects with circular references.
+ * Returns true if the object are equal.
+ */
+export declare function compareByNormalizedJsonValue<T>(v1: T | undefined, v2: T | undefined): boolean;
+/**
+ * Compares 2 objects by their normalized JSON value for specific fields only.
+ * This function should not be used with objects with circular references.
+ * Returns true if the specified fields are equal.
+ */
+export declare function compareByNormalizedJsonValueForFields<T>(v1: T | undefined, v2: T | undefined, fields: Array<keyof T>): boolean;

package/dist/internal-common/src/utils/squid.constants.d.ts

@@ -0,0 +1,3 @@
+export declare const SQUID_SUPPORT_EMAIL = "support@getsquid.ai";
+/** Error code when application is not found. */
+export declare const APPLICATION_NOT_FOUND_ERROR = "APPLICATION_NOT_FOUND";

package/dist/internal-common/src/utils/trace-id-generator.d.ts

@@ -0,0 +1 @@
+export declare function generateTraceId(prefix?: string): string;

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

@@ -0,0 +1,21 @@
+import { HttpStatusCode } from '../public-types/http-status.public-types';
+export declare class ValidationError extends Error {
+    readonly statusCode: HttpStatusCode;
+    readonly details?: any;
+    constructor(error: string, statusCode: HttpStatusCode, details?: Record<string, unknown>);
+}
+export declare function isValidId(id: unknown, maxLength?: number): boolean;
+export declare function validateFieldSort(fieldSort: unknown): void;
+/** The largest limit one query may carry. */
+export declare const MAX_QUERY_LIMIT = 20000;
+export declare function validateQueryLimit(limit: unknown): void;
+/**
+ * All type names returned by 'typeof' supported by JavaScript:
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof}.
+ * and a few other supported types.
+ */
+export type JavascriptTypeName = 'undefined' | 'object' | 'boolean' | 'number' | 'bigint' | 'string' | 'symbol' | 'function';
+/** Returns true if 'typeof' of the 'value' is 'type' or 'type[]'. */
+export declare function isRightType(value: unknown, type: JavascriptTypeName): boolean;
+/** Returns true if 'obj' has only keys listed in the 'keys'. Object can't be an array. */
+export declare function hasOnlyKeys(obj: object, keys: string[]): boolean;

package/dist/internal-common/src/websocket.impl.d.ts

@@ -0,0 +1,26 @@
+interface Options {
+    maxAttempts?: number;
+    protocols?: string[];
+    onmessage?: (event: any) => void;
+    onopen?: (event: any) => void;
+    onclose?: (event: any) => void;
+    onerror?: (event: any) => void;
+    onreconnect?: (event: any) => void;
+    onmaximum?: (event: any) => void;
+    timeoutMillis?: number;
+}
+export interface WebSocketWrapper {
+    open: () => void;
+    reconnect: (e: any) => void;
+    json: (x: any) => void;
+    send: (x: string) => void;
+    close: (x?: number, y?: string) => void;
+    connected: boolean;
+    /**
+     * Websocket is explicitly closed by calling socket.close().
+     * Used to ignore errors after socket.closed() is called.
+     */
+    closeCalled: boolean;
+}
+export declare function createWebSocketWrapper(url: string, opts?: Options): WebSocketWrapper;
+export {};

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

@@ -113,7 +113,7 @@ export declare class AiAgentReference {
      *   `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 AiChatModelSelection | undefined>(prompt: string, options?: AiChatOptionsWithoutVoice<T>, jobId?: JobId): Observable<string>;
+    chat<T extends AiAskModelSelection | 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.
@@ -132,6 +132,8 @@ export declare class AiAgentReference {
      *   knows it can look up the job’s status.
      */
     ask<T extends AiAskModelSelection | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<string>;
+    /** Returns the answer, annotations, routing information, and optional validation verdict. */
+    askWithResult<T extends AiAskModelSelection | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<AskResponse>;
     /**
      * Sends a prompt and returns the string response and file annotations.
      * @param prompt The text prompt to send to the agent.

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

@@ -1,5 +1,5 @@
 import { Observable } from 'rxjs';
-import { AiAnnotation, AiAskModelSelection, AiChatModelSelection, AiChatOptions, AiChatRequestCredentials, AiModelRoutingResult } from '../../../internal-common/src/public-types/ai-agent.public-types';
+import { AiAnnotation, AiAnswerValidationResult, AiAskModelSelection, AiChatModelSelection, AiChatOptions, AiChatRequestCredentials, AiModelRoutingResult } 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.
@@ -29,6 +29,8 @@ export interface TranscribeAndAskWithVoiceResponse {
  * @category AI
  */
 export interface AskResponse {
+    /** Judge verdict, present when answer validation is enabled. */
+    validation?: AiAnswerValidationResult;
     /** The main text response from the AI agent. */
     responseString: string;
     /** Optional annotations that provide additional context or metadata about the response. */
@@ -51,7 +53,7 @@ export interface AskWithVoiceResponse {
  * Chat options that exclude voice-specific configurations.
  * @category AI
  */
-export type AiChatOptionsWithoutVoice<T extends AiChatModelSelection | undefined = undefined> = Omit<AiChatOptions<T>, 'voiceOptions'> & {
+export type AiChatOptionsWithoutVoice<T extends AiAskModelSelection | undefined = undefined> = Omit<AiChatOptions<ConcreteModelOf<T>>, 'voiceOptions' | 'model'> & {
     model?: T;
 } & AiChatRequestCredentials;
 /**
@@ -69,7 +71,7 @@ export type AiAskOptionsWithVoice<T extends AiAskModelSelection | undefined = un
     model?: T;
 } & AiChatRequestCredentials;
 /**
- * The concrete model an ask's model selection names, which picks the provider-specific option set;
+ * The concrete model a request's model selection names, which picks the provider-specific option set;
  * a routing choice names none, so it gets the provider-agnostic options.
  * @category AI
  */

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

@@ -1,5 +1,5 @@
 import { Observable } from 'rxjs';
-import { AiEmbeddingsModelWithOptionalFields, AiKnowledgeBase, AiKnowledgeBaseChatOptions, AiKnowledgeBaseContext, AiKnowledgeBaseContextRequest, AiKnowledgeBaseContextWithReasoning, AiKnowledgeBaseDownloadContextResponse, AiKnowledgeBaseFileStatusInfo, AiKnowledgeBaseFolderStatusResponse, AiKnowledgeBaseSearchContextsWithContextIdRequest, AiKnowledgeBaseSearchContextsWithPromptRequest, AiKnowledgeBaseSearchResponse, AiKnowledgeBaseSearchResultChunk, BulkIngestionContext, BulkIngestionCreateUploadUrlsResponse, BulkIngestionJobStatusResponse, BulkIngestionUpsertContextsOptions, BulkIngestionUpsertContextsResponse, ExploreKnowledgeBaseGraphRequest, ExploreKnowledgeBaseGraphResponse, GenerateMetadataFieldDescriptionsRequest, GenerateMetadataFieldDescriptionsResponse, GetKnowledgeBaseGraphStatusResponse, GrepKnowledgeBaseOptions, GrepKnowledgeBaseResponse, ListAiKnowledgeBaseContextsPageResponse, ListKnowledgeBaseContextsOptions, QueryKnowledgeBaseGraphRequest, QueryKnowledgeBaseGraphResponse, RebuildKnowledgeBaseGraphRequest, UpsertKnowledgeBaseContextResponse, UpsertKnowledgeBaseContextsResponse } from '../../../internal-common/src/public-types/ai-knowledge-base.public-types';
+import { AiEmbeddingsModelWithOptionalFields, AiKnowledgeBase, AiKnowledgeBaseChatOptions, AiKnowledgeBaseContext, AiKnowledgeBaseContextRequest, AiKnowledgeBaseContextWithReasoning, AiKnowledgeBaseDownloadContextResponse, AiKnowledgeBaseFileStatusInfo, AiKnowledgeBaseFolderStatusResponse, AiKnowledgeBaseSearchContextsWithContextIdRequest, AiKnowledgeBaseSearchContextsWithPromptRequest, AiKnowledgeBaseSearchResponse, AiKnowledgeBaseSearchResultChunk, BulkIngestionContext, BulkIngestionCreateUploadUrlsResponse, BulkIngestionJobStatusResponse, BulkIngestionUpsertContextsOptions, BulkIngestionUpsertContextsResponse, ExploreKnowledgeBaseGraphRequest, ExploreKnowledgeBaseGraphResponse, GenerateMetadataFieldDescriptionsRequest, GenerateMetadataFieldDescriptionsResponse, GetKnowledgeBaseGraphStatusRequest, GetKnowledgeBaseGraphStatusResponse, GrepKnowledgeBaseOptions, GrepKnowledgeBaseResponse, ListAiKnowledgeBaseContextsPageResponse, ListKnowledgeBaseContextsOptions, QueryKnowledgeBaseGraphRequest, QueryKnowledgeBaseGraphResponse, RebuildKnowledgeBaseGraphRequest, UpsertKnowledgeBaseContextResponse, UpsertKnowledgeBaseContextsResponse } from '../../../internal-common/src/public-types/ai-knowledge-base.public-types';
 import { AiContextId } from '../../../internal-common/src/public-types/communication.public-types';
 /**
  * Parameters for creating or updating an AI agent.
@@ -197,16 +197,17 @@ export declare class AiKnowledgeBaseReference {
     /**
      * Queries the knowledge base's graph (documents, entities, themes, facets) through the closed op set
      * — overview / resolve / describe / subtree / docsUnder / conceptsOf / neighborhood / pathBetween /
-     * globalSummary. Requires `graphRag.enabled` on the knowledge base. Refused on a knowledge base with
-     * `accessControl.mode: 'enforced'` — the graph carries no access scopes, so its answers cannot be
-     * filtered per caller.
+     * globalSummary / relationship. Requires `graphRag.enabled` on the knowledge base. Refused on a knowledge
+     * base with `accessControl.mode: 'enforced'` — the graph carries no access scopes, so its answers cannot
+     * be filtered per caller.
      */
     queryGraph(request: Omit<QueryKnowledgeBaseGraphRequest, 'knowledgeBaseId'>): Promise<QueryKnowledgeBaseGraphResponse>;
     /**
      * Returns the knowledge base's graph build/readiness status: counts, facets, staleness, the most
      * recent rebuild job, and the graph's LLM token/cost usage (`ingestUsage`, `lastRebuildUsage`).
+     * Pass `includeTopics: false` to poll it without the topic table.
      */
-    getGraphStatus(): Promise<GetKnowledgeBaseGraphStatusResponse>;
+    getGraphStatus(options?: Omit<GetKnowledgeBaseGraphStatusRequest, 'knowledgeBaseId'>): Promise<GetKnowledgeBaseGraphStatusResponse>;
     /**
      * Looks up the durable ingestion status of one file by path (`folderPath/filename`, or just
      * `filename` at the upload root): `'completed'`, `'failed'` (with `errorMessage`/`errorCode`),
@@ -231,8 +232,9 @@ export declare class AiKnowledgeBaseReference {
      */
     rebuildGraph(request?: Omit<RebuildKnowledgeBaseGraphRequest, 'knowledgeBaseId'>): Promise<void>;
     /**
-     * Returns a bounded slice of the knowledge base's entity graph (highest-degree entities and the
-     * relationships among them) for exploration/visualization. Requires `graphRag.enabled`.
+     * Returns a bounded slice of the knowledge base's entity graph for exploration/visualization: the
+     * highest-degree entities, a topic's members, an entity's neighborhood or a name search, optionally
+     * narrowed by a context metadata filter, with the relationships among them. Requires `graphRag.enabled`.
      */
     exploreGraph(request?: Omit<ExploreKnowledgeBaseGraphRequest, 'knowledgeBaseId'>): Promise<ExploreKnowledgeBaseGraphResponse>;
     /**

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

@@ -13,7 +13,7 @@ export declare class LangGraphReference {
      *
      * For very long graphs where you don't want to hold a Promise, use `invokeAsync()` instead.
      *
-     * @param options Initial state, optional thread to run against and optional timeout of the run.
+     * @param options Initial state, optional thread to run against, and optional timeout and context of the run.
      */
     invoke(options?: InvokeLangGraphOptions): Promise<InvokeLangGraphSuccessResult>;
     /**
@@ -22,7 +22,7 @@ export declare class LangGraphReference {
      *
      * Use this for graphs that may run longer than is comfortable to hold a Promise for.
      *
-     * @param options Initial state, optional thread to run against and optional timeout of the run.
+     * @param options Initial state, optional thread to run against, and optional timeout and context of the run.
      */
     invokeAsync(options?: InvokeLangGraphOptions): Promise<JobId>;
     /**
@@ -31,7 +31,7 @@ export declare class LangGraphReference {
      *
      * @param threadId The thread to resume.
      * @param resumePayload Value passed to the `interrupt()` call inside the graph.
-     * @param options Optional timeout of the resumed run.
+     * @param options Optional timeout and context of the resumed run.
      */
     resume(threadId: string, resumePayload: unknown, options?: ResumeLangGraphOptions): Promise<InvokeLangGraphSuccessResult>;
     /**
@@ -40,7 +40,7 @@ export declare class LangGraphReference {
      *
      * @param threadId The thread to resume.
      * @param resumePayload Value passed to the `interrupt()` call inside the graph.
-     * @param options Optional timeout of the resumed run.
+     * @param options Optional timeout and context of the resumed run.
      */
     resumeAsync(threadId: string, resumePayload: unknown, options?: ResumeLangGraphOptions): Promise<JobId>;
     /** Returns the current state of a LangGraph thread. */

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

package/package.json

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