@squidcloud/client 1.0.72 → 1.0.74

package/dist/index.js.LICENSE.txt

@@ -1,20 +1,3 @@
-/*! *****************************************************************************
-Copyright (c) Microsoft Corporation.
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
-***************************************************************************** */
-
-/*! ieee754. BSD-3-Clause License. Feross Aboukhadijeh <https://feross.org/opensource> */
-
 /**
  * @license
  * Lodash <https://lodash.com/>

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

@@ -1,66 +1,167 @@
-import { AiAssistantMutateRequest, IntegrationId, OpenAiModelName } from '@squidcloud/common';
+import { IntegrationId, OpenAiModelName } from '@squidcloud/common';
 import { Observable } from 'rxjs';
-import { ClientIdService } from './client-id.service';
 import { RpcManager } from './rpc.manager';
 import { SocketManager } from './socket.manager';
 export declare class AiAssistantClient {
-    private readonly clientIdService;
     private readonly rpcManager;
     private readonly socketManager;
     private readonly integrationId;
     private readonly ongoingChatRequests;
-    constructor(clientIdService: ClientIdService, rpcManager: RpcManager, socketManager: SocketManager, integrationId: IntegrationId);
-    profile(id: string): AiAssistantProfileClient;
-    mutate(request: AiAssistantMutateRequest): Promise<void>;
+    constructor(rpcManager: RpcManager, socketManager: SocketManager, integrationId: IntegrationId);
+    /**
+     * Retrieves a profile reference for the provided id. A profile reference
+     * can be used to create and update profiles, add instructions and context
+     * and start chats.
+     *
+     * @param id - The id of the profile.
+     * @returns The profile reference.
+     */
+    profile(id: string): AiAssistantProfileReference;
+    /**
+     * Sends a prompt to the specified profile id.
+     *
+     * @param profileId - The profile id.
+     * @param prompt - The prompt.
+     * @returns An observable that emits when a new response token is received. The emitted value is the entire response
+     * that has been received so far.
+     */
     chat(profileId: string, prompt: string): Observable<string>;
     private handleChatResponse;
 }
-declare class AiAssistantProfileClient {
+declare class AiAssistantProfileReference {
     private readonly client;
     private readonly integrationId;
     private readonly profileId;
     constructor(client: AiAssistantClient, integrationId: IntegrationId, profileId: string);
+    /**
+     * Sends a prompt to the current profile.
+     *
+     * @param prompt - The prompt.
+     * @returns An observable that emits when a new response token is received. The emitted value is the entire response
+     * that has been received so far.
+     */
     chat(prompt: string): Observable<string>;
-    context(id?: string): AiAssistantContextClient;
-    instruction(id?: string): AiAssistantInstructionClient;
+    /**
+     * Retrieves a context reference for the current profile. A context reference can be used to add a new context entry
+     * to the profile, or update/delete an existing entry context.
+     *
+     * @param id - The id of the context entry. If no id is passed, an id will be
+     * generated and the reference will point to a new context entry.
+     * @returns The context reference.
+     */
+    context(id?: string): AiAssistantContextReference;
+    /**
+     * Retrieves an instruction reference for the current profile. An instruction reference can be used to add a new
+     * instruction entry to the profile, or update/delete an existing instruction entry.
+     *
+     * @param id - The id of the instruction entry. If no id is passed, an id will be
+     * generated and the reference will point to a new instruction entry.
+     * @returns The instruction reference.
+     */
+    instruction(id?: string): AiAssistantInstructionReference;
+    /**
+     * Adds a new profile to the assistant. This will result in an error if a profile already exists with the same id.
+     *
+     * @param data An object containing options for creating the profile.
+     * @param data.modelName - The name of the OpenAI model (`gpt-3.5 or `gpt-4`).
+     * @returns A promise that resolves when the profile is successfully created.
+     */
     insert(data: {
         modelName: OpenAiModelName;
-        strictContext: boolean;
     }): Promise<void>;
+    /**
+     * Updates an existing assistant profile. This will result in an error if a profile has not yet been created for the
+     * current profile id.
+     *
+     * @param data An object containing options for updating the profile.
+     * @param data.modelName - The name of the OpenAI model (`gpt-3.5 or `gpt-4`).
+     * @returns A promise that resolves when the profile is successfully updated.
+     */
     update(data: {
-        modelName?: OpenAiModelName;
-        strictContext: boolean;
+        modelName: OpenAiModelName;
     }): Promise<void>;
+    /**
+     * Deletes an existing assistant profile. This will result in an error if a profile has not yet been created for the
+     * current profile id.
+     *
+     * @returns A promise that resolves when the profile is successfully deleted.
+     */
     delete(): Promise<void>;
 }
-declare class AiAssistantContextClient {
+declare class AiAssistantContextReference {
     private readonly client;
     private readonly integrationId;
     private readonly profileId;
     private readonly id;
     constructor(client: AiAssistantClient, integrationId: IntegrationId, profileId: string, id?: string);
+    /**
+     * Adds a new context entry to the assistant profile. This will result in an error if an entry already exists with
+     * the same id.
+     *
+     * @param data An object containing options for creating the entry.
+     * @param data.title - The title of the entry.
+     * @param data.context - The context data.
+     * @returns A promise that resolves when the context is successfully created.
+     */
     insert(data: {
         title: string;
         context: string;
     }): Promise<void>;
+    /**
+     * Updates an existing context entry on the assistant profile. This will result in an error if an entry has not yet
+     * been created for the current context id.
+     *
+     * @param data An object containing options for updated the entry.
+     * @param data.title - The title of the entry.
+     * @param data.context - The context data.
+     * @returns A promise that resolves when the context is successfully updated.
+     */
     update(data: {
         title?: string;
         context?: string;
     }): Promise<void>;
+    /**
+     * Deletes an existing context entry on the assistant profile. This will result in an error if an entry has not yet
+     * been created for the current context id.
+     *
+     * @returns A promise that resolves when the context is successfully deleted.
+     */
     delete(): Promise<void>;
 }
-declare class AiAssistantInstructionClient {
+declare class AiAssistantInstructionReference {
     private readonly client;
     private readonly integrationId;
     private readonly profileId;
     private readonly id;
     constructor(client: AiAssistantClient, integrationId: IntegrationId, profileId: string, id?: string);
+    /**
+     * Adds a new instruction entry to the assistant profile. This will result in an error if an entry already exists with
+     * the same id.
+     *
+     * @param data An object containing options for creating the entry.
+     * @param data.instruction - The instruction data.
+     * @returns A promise that resolves when the instruction is successfully created.
+     */
     insert(data: {
         instruction: string;
     }): Promise<void>;
+    /**
+     * Updates an existing instruction entry on the assistant profile. This will result in an error if an entry has not
+     * yet been created for the current instruction id.
+     *
+     * @param data An object containing options for updated the entry.
+     * @param data.instruction - The instruction data.
+     * @returns A promise that resolves when the instruction is successfully updated.
+     */
     update(data: {
         instruction: string;
     }): Promise<void>;
+    /**
+     * Deletes an existing instruction entry on the assistant profile. This will result in an error if an entry has not
+     * yet been created for the current instruction id.
+     *
+     * @returns A promise that resolves when the instruction is successfully deleted.
+     */
     delete(): Promise<void>;
 }
 export {};

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

@@ -2,12 +2,10 @@ import { IntegrationId } from '@squidcloud/common';
 import { AiAssistantClient } from './ai-assistant-client';
 import { RpcManager } from './rpc.manager';
 import { SocketManager } from './socket.manager';
-import { ClientIdService } from './client-id.service';
 export declare class AiClientFactory {
-    private readonly clientIdService;
     private readonly rpcManager;
     private readonly socketManager;
     private readonly assistantsMap;
-    constructor(clientIdService: ClientIdService, rpcManager: RpcManager, socketManager: SocketManager);
+    constructor(rpcManager: RpcManager, socketManager: SocketManager);
     getAssistant(integrationId: IntegrationId): AiAssistantClient;
 }

package/dist/typescript-client/src/client-id.service.d.ts

@@ -12,8 +12,9 @@ import { DestructManager } from './destruct.manager';
 export declare class ClientIdService {
     private readonly destructManager;
     private readonly clientTooOldSubject;
-    private clientId;
+    private readonly clientIdSubject;
     constructor(destructManager: DestructManager);
+    observeClientId(): Observable<ClientId>;
     observeClientTooOld(): Observable<void>;
     /**  there was a long-term disconnection of the socket */
     notifyClientTooOld(): void;

package/dist/typescript-client/src/connection-details.d.ts

@@ -0,0 +1,23 @@
+import { ClientId } from '@squidcloud/common';
+import { Observable } from 'rxjs';
+/**
+ * Provides information about the connection to the Squid Server.
+ */
+export declare class ConnectionDetails {
+    private readonly clientIdService;
+    private readonly socketManager;
+    private isConnected;
+    /** Whether the Squid Client SDK is currently connected to the Squid Server. */
+    get connected(): boolean;
+    /**
+     * A unique client ID that is assigned to the client. This client ID is also available to the different backend
+     * function in the context object.
+     * Note: The client ID may change after a long disconnect.
+     */
+    get clientId(): ClientId;
+    /**
+     * Returns an observable that emits true when the client is connected to the server and false when the client is
+     * disconnected from the server.
+     */
+    observeConnected(): Observable<boolean>;
+}

package/dist/typescript-client/src/destruct.manager.d.ts

@@ -5,7 +5,7 @@ export declare class DestructManager {
     private readonly destructors;
     private readonly isDestructedSubject;
     get isDestructing(): boolean;
-    get isDestructingObservable(): Observable<boolean>;
+    observeIsDestructing(): Observable<void>;
     onPreDestruct(fn: DestructorFn): void;
     onDestruct(fn: DestructorFn): void;
     destruct(): Promise<void>;

package/dist/typescript-client/src/mutation/mutation-sender.d.ts

@@ -1,12 +1,10 @@
 import { IntegrationId, LockManager, MutateResponse, Mutation } from '@squidcloud/common';
 import { QuerySubscriptionManager } from '../query/query-subscription.manager';
 import { RpcManager } from '../rpc.manager';
-import { ClientIdService } from '../client-id.service';
 export declare class MutationSender {
-    private readonly clientIdService;
     private readonly rpcManager;
     private readonly lockManager;
     private readonly querySubscriptionManager;
-    constructor(clientIdService: ClientIdService, rpcManager: RpcManager, lockManager: LockManager, querySubscriptionManager: QuerySubscriptionManager);
+    constructor(rpcManager: RpcManager, lockManager: LockManager, querySubscriptionManager: QuerySubscriptionManager);
     sendMutations(mutations: Array<Mutation>, integrationId: IntegrationId): Promise<MutateResponse>;
 }

package/dist/typescript-client/src/named-query.manager.d.ts

@@ -2,13 +2,11 @@ import { IntegrationId, QueryName } from '@squidcloud/common';
 import { Observable } from 'rxjs';
 import { RpcManager } from './rpc.manager';
 import { SocketManager } from './socket.manager';
-import { ClientIdService } from './client-id.service';
 export declare class NamedQueryManager {
-    private readonly clientIdService;
     private readonly rpcManager;
     private readonly socketManager;
     private readonly ongoingNamedQueryExecutions;
-    constructor(clientIdService: ClientIdService, rpcManager: RpcManager, socketManager: SocketManager);
+    constructor(rpcManager: RpcManager, socketManager: SocketManager);
     executeNamedQueryAndSubscribe<T>(integrationId: IntegrationId, queryName: QueryName, params: Record<string, any>): Observable<T>;
     private handleNamedQueryResponse;
 }

package/dist/typescript-client/src/query/join-query-builder.factory.d.ts

@@ -1,4 +1,4 @@
-import { DocumentData, FieldName, Operator, PrimitiveFieldType } from '@squidcloud/common';
+import { BaseQueryBuilderInterface, DocumentData, FieldName, Operator, PrimitiveFieldType } from '@squidcloud/common';
 import { Observable } from 'rxjs';
 import { DocumentReference } from '../document-reference';
 import { Alias } from './query.types';
@@ -7,7 +7,7 @@ import { Alias } from './query.types';
  * To learn more about join queries, see
  * {@link https://docs.squid.cloud/docs/client-sdk/queries#joining-data-across-collections-and-integrations}.
  */
-export declare class JoinQueryBuilder<DocumentType extends DocumentData, MyAlias extends Alias, ReturnType extends Record<MyAlias, DocumentReference<DocumentType> | undefined>> {
+export declare class JoinQueryBuilder<DocumentType extends DocumentData, MyAlias extends Alias, ReturnType extends Record<MyAlias, DocumentReference<DocumentType> | undefined>> extends BaseQueryBuilderInterface<ReturnType> {
     private readonly collectionName;
     private readonly integrationId;
     private readonly querySubscriptionManager;

package/dist/typescript-client/src/query/query-builder.factory.d.ts

@@ -44,11 +44,17 @@ export declare class QueryBuilder<DocumentType extends DocumentData> extends Sim
     private readonly documentReferenceFactory;
     private readonly queryBuilderFactory;
     private readonly documentIdentityService;
+    private forceFetchFromServer;
     getSortOrder(): FieldSort<DocumentType>[];
     /**
      * @inheritDoc
      */
     snapshot(): Promise<Array<DocumentReference<DocumentType>>>;
+    /**
+     * Forces the query to return data from the server even if there is a query that already returned the requested
+     * result.
+     */
+    setForceFetchFromServer(): this;
     /**
      * @inheritDoc
      */

package/dist/typescript-client/src/query/query-subscription.manager.d.ts

@@ -12,9 +12,24 @@ export declare class QuerySubscriptionManager {
     private readonly documentStore;
     private readonly destructManager;
     private readonly documentIdentityService;
+    /**
+     * As long as there are mutations in flight we do not want to send queries because it causes race conditions,
+     * preventing parallel queries and mutations simplifies the mental model.
+     */
     readonly safeToSendQueriesToServer: BehaviorSubject<boolean>;
+    /**
+     * An observable used by the data manager, the query subscription manager (this class) identifies when a document no
+     * longer has queries that it is part of their result, such document is considered orphan. The data manager will mark
+     * as orphan.
+     */
     onOrphanDocuments: Subject<string[]>;
+    /** All the currently running queries with their full state. */
     private readonly ongoingQueries;
+    /**
+     * The number of queries that are currently in-flight (about to be sent to the server or sent but did not get a
+     * response yet). This is used by the data manager to prevent it from sending mutations while there are in-flight
+     * queries.
+     */
     private readonly inflightQueriesCount;
     /**
      * The two maps below maintain the relation between document ids we know about locally to clientRequestIds (queries).
@@ -22,11 +37,31 @@ export declare class QuerySubscriptionManager {
      */
     private readonly clientRequestIdToLocalDocuments;
     private readonly localDocumentToClientRequestIds;
+    /**
+     * A data structure for mapping queries to allow reverse queries search (given a document, find all the matching
+     * queries)
+     */
     private readonly queryMappingManager;
     constructor(rpcManager: RpcManager, clientIdService: ClientIdService, documentStore: DocumentStore, destructManager: DestructManager, documentIdentityService: DocumentIdentityService);
+    /**
+     * Returns true if the client knows about this clientRequestId. It may happen that it will return false in the case
+     * that the client unsubscribed from a query but the server sent a mutation update for this clientRequestId.
+     */
     hasOngoingQuery(clientRequestId: ClientRequestId): boolean;
+    /**
+     * Returns the query associated with the given clientRequestId. Throws error if the clientRequestId is not known.
+     */
     getQuery(clientRequestId: ClientRequestId): Query;
-    setGotResponseFromServer(clientRequestId: ClientRequestId): void;
+    /**
+     * A query receives updates from two different sources:
+     * 1 - An initial snapshot from the server or from a parent query
+     * 2 - Incremental updates from the server (or from a parent query before the query is registered)
+     *
+     * If an incremental update is received before the snapshot was received, we cannot process it for this query.
+     * This boolean indicates whether the initial snapshot was received.
+     */
+    setGotInitialResult(clientRequestId: ClientRequestId): void;
+    /** Given a document, returns all the queries that should be notified with the new document properties. */
     findQueriesForDocument(doc: SquidDocument, squidDocId: SquidDocId): Array<QuerySubscriptionId>;
     /**
      * Given the new document's properties, finds all the queries that should be notified with the new properties and
@@ -35,12 +70,33 @@ export declare class QuerySubscriptionManager {
      * will need to be notified due to the change of properties).
      */
     setClientRequestIdsForLocalDoc(squidDocId: SquidDocId, properties: SquidDocument | undefined): Array<ClientRequestId>;
+    /**
+     * Due to an error when syncing a document, all the queries that are subscribed to this document should be notified
+     * and error out.
+     */
     errorOutAllQueries(squidDocId: SquidDocId, err: any): void;
+    /** Notifies to all the given queries (identified by their clientRequestId) with the updated query result. */
     notifyAllSubscriptions(clientRequestIds: ClientRequestId[]): void;
-    processQuery(query: Query, rootAlias: Alias, joins: Record<string, Query>, joinConditions: Record<Alias, JoinCondition>, subscribe: boolean): Observable<Array<Record<Alias, SquidDocument | undefined>>>;
+    /**
+     * Given an ongoing query, search for candidate ongoing queries that can serve as a parent.
+     * If there is a parent query, the result of that query can be used for serving the current query.
+     * We will still register the current query on the server, but we do not need to run the query, apply security rules,
+     * etc.
+     */
+    private findValidParentQuery;
+    processQuery(query: Query, rootAlias: Alias, joins: Record<string, Query>, joinConditions: Record<Alias, JoinCondition>, subscribe: boolean, forceFetchFromServer: boolean): Observable<Array<Record<Alias, SquidDocument | undefined>>>;
+    /**
+     * Returns whether the given document ID has a query that has this document ID as a result.
+     * A document without a query is considered "un-tracked".
+     */
     hasOngoingQueryForDocId(squidDocId: string): boolean;
+    /**
+     * Removes a query from the mapping and updates the orphan documents as needed.
+     */
     private removeClientRequestIdMapping;
+    /** Will resolve once all the in-flight queries are done. */
     waitForAllQueriesToFinish(): Promise<void>;
+    /** Register logic for cleaning up the query when it is unsubscribed. */
     private registerQueryFinalizer;
     /** Creates a graph of ongoing queries and returns the root of the graph. */
     private createOngoingQueryGraph;
@@ -49,16 +105,31 @@ export declare class QuerySubscriptionManager {
     private join;
     private getOngoingQueriesBfs;
     private updateOngoingQueryWithNewDataFromSupportingQuery;
-    private allOngoingQueriesGotServerResult;
+    private allOngoingQueriesGotInitialResult;
     private completeAllSupportedQueries;
     private predestruct;
     unsubscribe(): void;
     hasSubscription(clientRequestId: ClientRequestId): boolean;
     /** Sends the query request to the server and makes sure to unsubscribe once the subject completes. */
-    private sendQueryToServer;
+    private sendQueryToServerOrUseParentQuery;
     /**
-     * naive way to refresh queries/subscriptions when we have a new client id
+     * Uses the parent query as the source of data for the given ongoing query until the ongoing query is registered on
+     * the server. It prevents the parent query from being unsubscribed until the query is registered on the server and
+     * the first snapshot is received from the parent query.
+     * 1 - Prevents the parent query from being unsubscribed
+     * 2 - Connects the results of the parent query to the result of the current ongoing query
+     * 3 - Registers the query on the server
      */
+    private useParentOngoingQuery;
+    /**
+     * Sends the /query request to the server. It:
+     * 1 - Waits for when it is safe to send a query to the server (no in-flight mutations)
+     * 2 - Increments the number of inflightQueriesCount to prevent parallel mutations
+     * 3 - Handles errors
+     * 4 - Marks the query as registered
+     */
+    private sendQueryToServer;
+    /** naive way to refresh queries/subscriptions when we have a new client id */
     private refreshOngoingQueries;
     private migrateDocIds;
 }

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

@@ -1,9 +1,11 @@
 import { ApiEndpointId, ApiKey, AppId, CollectionName, DocumentData, EnvironmentId, IntegrationId, QueryName, SquidDeveloperId, SupportedSquidRegion } from '@squidcloud/common';
 import { Observable } from 'rxjs';
+import { AiAssistantClient } from './ai-assistant-client';
 import { CollectionReference } from './collection-reference';
 import { DistributedLock } from './distributed-lock.manager';
 import { GraphQLClient } from './graphql-client';
 import { TransactionId } from './types';
+import { ConnectionDetails } from './connection-details';
 /** The different options that can be used to initialize a Squid instance. */
 export interface SquidOptions {
     /**
@@ -68,6 +70,7 @@ export declare class Squid {
     private readonly authManager;
     private readonly clientIdService;
     private readonly aiClientFactory;
+    private readonly _connectionDetails;
     private static readonly squidInstancesMap;
     /**
      * Creates a new instance of Squid with the given options.
@@ -175,6 +178,23 @@ export declare class Squid {
      * @returns A GraphQL client for the given integration.
      */
     graphql: (integrationId: IntegrationId) => GraphQLClient;
+    /**
+     * Returns a set of AI specific clients. Currently, the only supported client is the AI Assistant, which is accessed
+     * through the `assistant`.
+     *
+     * @returns A set of AI specific clients.
+     */
+    ai: () => {
+        /**
+         * Returns an AI Assistant client for the given integration. The AI Assistant client can be used to build and chat
+         * with custom AI profiles. For more information about the AI Assistant in Squid, please refer to the documentation
+         * at {@link https://docs.squid.cloud/docs/integrations/ai/ai-assistant}.
+         *
+         * @param integrationId The id of the AI Assistant integration.
+         * @returns An AI Assistant client.
+         */
+        assistant: (integrationId: IntegrationId) => AiAssistantClient;
+    };
     /**
      * Returns a distributed lock for the given mutex. The lock can be used to synchronize access to a shared resource.
      * The lock will be released when the release method on the returned object is invoked or whenever the connection
@@ -192,5 +212,7 @@ export declare class Squid {
      * @returns A promise that resolves when the destruct process is complete.
      */
     destruct: () => Promise<void>;
+    /** Provides information about the connection to the Squid Server. */
+    connectionDetails: () => ConnectionDetails;
     private validateNotDestructed;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/client",
-  "version": "1.0.72",
+  "version": "1.0.74",
   "description": "A typescript implementation of the Squid client",
   "main": "dist/index.js",
   "types": "dist/typescript-client/src/index.d.ts",

package/dist/common/src/auth.types.d.ts

@@ -1 +0,0 @@
-export {};