@squidcloud/client 1.0.501 → 1.0.502

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

@@ -0,0 +1,4 @@
+import { AppId } from '../public-types/communication.public-types';
+import { Stage } from '../types/stage';
+export declare function getEnvironmentPrefix(shard: string | undefined, region: string, cloudId: string, stage: Stage): string;
+export declare function getApplicationUrl(environmentPrefix: string, appId: string, path: string, appIdPlaceholder?: AppId, environmentPrefixPlaceholder?: string): 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/internal-common/src/utils/lock.manager.d.ts

@@ -0,0 +1,14 @@
+type LockMutex = string;
+/**
+ * A simple lock manager that locks a list of mutexes.
+ * When locking a list of mutexes, the lock will start only when all the mutexes are available - preventing partial lock
+ * and potential deadlocks.
+ */
+export declare class LockManager {
+    private readonly locks;
+    lock(...mutexes: LockMutex[]): Promise<void>;
+    release(...mutexes: LockMutex[]): void;
+    canGetLock(...mutexes: LockMutex[]): boolean;
+    lockSync(...mutexes: LockMutex[]): void;
+}
+export {};

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

@@ -0,0 +1,4 @@
+import { QueryMetricsRequestCommon, QueryMetricsResultGroup } from '../public-types/metric.public-types';
+export type QueryMetricsRequestIntervals = Required<Pick<QueryMetricsRequestCommon, 'fillValue' | 'fn' | 'groupByTags' | 'periodEndSeconds' | 'periodStartSeconds' | 'pointIntervalAlignment' | 'pointIntervalSeconds' | 'tagDomains' | 'noDataBehavior'>>;
+/** Adds missed known tag domain groups and fills all missed points with a request.fillValue. */
+export declare function fillMissedPoints(request: QueryMetricsRequestIntervals, resultGroups: Array<QueryMetricsResultGroup>): void;

package/dist/internal-common/src/utils/metrics.types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type suffixes defines the type of the metric and can be used for
+ * metric value validation for incoming metrics.
+ */
+export declare const SQUID_METRIC_TYPE_SUFFIXES: readonly ["_count", "_time", "_size", "_entries", "_value"];
+/** Returns true if the given metric has a valid metric type. */
+export declare function hasValidMetricTypeSuffix(metricName: string): boolean;

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/integration-client.d.ts

@@ -1,4 +1,4 @@
-import { ConnectorPathStatusResult, DiscoverSourceRepositoriesResponse, IntegrationId, IntegrationInfo, IntegrationType } from './public-types';
+import { ConnectorPathStatusResult, DiscoverSourceRepositoriesResponse, IntegrationId, IntegrationInfo, IntegrationType, JobId } from './public-types';
 /**
  * IntegrationClient manages integrations within an application,
  * providing methods for listing, retrieving, updating, and deleting integrations.
@@ -136,6 +136,32 @@ export declare class IntegrationClient {
      * @returns A promise that resolves with the discovered schema and collection readiness information.
      */
     discoverDataConnectionSchema<SchemaType = Record<string, any>>(integrationId: IntegrationId): Promise<DiscoverDataConnectionSchemaResponse<SchemaType>>;
+    /**
+     * Starts inferring relationships from the data of a database integration, in the background, over its
+     * stored schema. It finds relationships no foreign key declares, discriminator columns, and columns that
+     * depend on each other, and writes the findings at the minimum confidence or above into the stored schema.
+     * Fails while another run of the integration is active.
+     *
+     * @param integrationId - The ID of the database integration.
+     * @param options - (Optional) What to look for and how much to spend on it.
+     * @returns A promise that resolves with the run's job ID, for `squid.jobs().awaitJob(jobId)`.
+     */
+    startRelationshipInference(integrationId: IntegrationId, options?: RelationshipInferenceOptions): Promise<JobId>;
+    /**
+     * Returns the latest relationship-inference run of a database integration, with its progress and findings.
+     *
+     * @param integrationId - The ID of the database integration.
+     * @returns A promise that resolves with the run, or `undefined` when the integration never had one.
+     */
+    getRelationshipInference<ItemType = Record<string, any>>(integrationId: IntegrationId): Promise<RelationshipInferenceRun<ItemType> | undefined>;
+    /**
+     * Stops the active relationship-inference run of a database integration. The run still writes what it
+     * found so far, and ends as 'cancelled'.
+     *
+     * @param integrationId - The ID of the database integration.
+     * @returns A promise that resolves when the run is asked to stop.
+     */
+    cancelRelationshipInference(integrationId: IntegrationId): Promise<void>;
     /**
      * Tests a data connection (database) to verify it is working.
      * Attempts to connect to the database and perform a basic operation to validate connectivity.
@@ -292,6 +318,104 @@ export interface DiscoverDataConnectionSchemaResponse<SchemaType = Record<string
      * Information about collection readiness for CRUD operations and replication.
      */
     collectionReadiness: Record<string, CollectionReadiness>;
+    /**
+     * What discovery could not read, such as the declared foreign keys, and kept as it was.
+     */
+    warnings?: string[];
+}
+/**
+ * Options for a relationship-inference run.
+ * @category Platform
+ */
+export interface RelationshipInferenceOptions {
+    /** What to look for. Defaults to all three. */
+    kinds?: Array<'relationships' | 'dependencies' | 'discriminators'>;
+    /** Collections to examine, on both sides. Defaults to every collection in the schema. */
+    collections?: string[];
+    /** Instructions about the data, for the AI; given, they turn `useAi` on. */
+    instructions?: string;
+    /** Lets the AI propose relationships that names miss, settle close calls, and describe the associations it adds. Off by default. */
+    useAi?: boolean;
+    /** The lowest confidence written to the schema. Defaults to 'medium'. */
+    minConfidence?: 'high' | 'medium' | 'low';
+    /** Rows sampled per collection; every finding is judged on them. Defaults to 1,000. */
+    sampleSize?: number;
+    /** Also checks every finding on all rows, at one more query each. Off by default. */
+    verifyOnAllRows?: boolean;
+    /** When the run stops and keeps what it has: 60 minutes by default, or 240 with `verifyOnAllRows`; at most 1,440. */
+    maxDurationMinutes?: number;
+    /** Queries in flight at once. Defaults to 2; at most 8 and the integration's pool size. */
+    concurrency?: number;
+}
+/**
+ * A relationship-inference run of a database integration.
+ * @category Platform
+ */
+export interface RelationshipInferenceRun<ItemType = Record<string, any>> {
+    /** The ID of the database integration. */
+    integrationId: IntegrationId;
+    /** Whether the run is still going, and how it ended. */
+    status: 'running' | 'completed' | 'cancelled' | 'failed';
+    /** What the run does now, or 'done'. */
+    phase: 'profiling' | 'matching' | 'in-table' | 'verifying' | 'describing' | 'applying' | 'done';
+    /** The options the run was started with. */
+    options: RelationshipInferenceOptions;
+    /** How far the run got. */
+    progress: RelationshipInferenceProgress;
+    /** When the run started, in milliseconds since the epoch. */
+    startedAt: number;
+    /** When the run ended, in milliseconds since the epoch. */
+    endedAt?: number;
+    /** True when the time budget or a cancel ended the run before it judged every candidate. */
+    partial: boolean;
+    /** Why the run failed. */
+    error?: string;
+    /** Everything the run found, whether or not it went into the schema. Empty until the run ends. */
+    findings: Array<RelationshipInferenceFinding<ItemType>>;
+    /** Signatures of earlier inferred items this complete run did not find again, which it removed from the stored schema. */
+    removed?: Array<string>;
+}
+/**
+ * How far a relationship-inference run got.
+ * @category Platform
+ */
+export interface RelationshipInferenceProgress {
+    /** Collections to sample. */
+    collections: number;
+    /** Collections sampled so far. */
+    collectionsProfiled: number;
+    /** Key columns to check referencing columns against. */
+    keys: number;
+    /** Key columns checked so far. */
+    keysProbed: number;
+    /** Findings to check on all rows, with `verifyOnAllRows`. */
+    findingsToVerify: number;
+    /** Findings checked on all rows so far. */
+    findingsVerified: number;
+    /** Queries sent to the database so far. */
+    queries: number;
+}
+/**
+ * One thing a relationship-inference run found.
+ * @category Platform
+ */
+export interface RelationshipInferenceFinding<ItemType = Record<string, any>> {
+    /** Identifies the finding; without its kind prefix, it is the item's key in the schema. */
+    signature: string;
+    /** Which of `association`, `discriminator` and `dependency` holds the finding. */
+    kind: 'association' | 'discriminator' | 'dependency';
+    /** Whether the finding passed every check at the minimum confidence or above. */
+    eligible?: boolean;
+    /** Whether the finding went into the stored schema. */
+    applied: boolean;
+    /** Why the finding did not go into the stored schema. */
+    notAppliedReason?: string;
+    /** A relationship between two collections, as the schema's `associations` hold it. */
+    association?: ItemType;
+    /** A column whose value decides what the rest of its row means, as the schema's `discriminators` hold it. */
+    discriminator?: ItemType;
+    /** Two columns of a row that fix each other, as the schema's `columnDependencies` hold it. */
+    dependency?: ItemType;
 }
 /**
  * Response from testing a data 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.501";
+export declare const SQUIDCLOUD_CLIENT_PACKAGE_VERSION = "1.0.502";

package/package.json

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