@squidcloud/backend 1.0.145 → 1.0.146-beta

package/dist/backend/src/index.d.ts

@@ -1,3 +1,7 @@
-export * from './actions';
-export * from './project';
-export * from './service';
+export * from './actions';
+export * from './llm-service';
+export * from './metadata';
+export * from './project';
+export * from './public-types';
+export * from './squid.service';
+export * from './utils';

package/dist/backend/src/llm-service.d.ts

@@ -0,0 +1,13 @@
+import { UserAiAskResponse, UserAiChatOptions } from '@squidcloud/client';
+import { SquidService } from './squid.service';
+/**
+ * Abstract class representing a service for interacting with LLMs (Large Language Models).
+ */
+export declare abstract class SquidLlmService extends SquidService {
+    /**
+     * Sends a prompt to the LLM and returns the response.
+     * @param prompt The prompt to send to the LLM.
+     * @param options Chat options to specify additional parameters for the request.
+     */
+    abstract ask(prompt: string, options: UserAiChatOptions): Promise<UserAiAskResponse>;
+}

package/dist/backend/src/metadata.d.ts

@@ -1,273 +1 @@
-import { AiChatbotActionType, AiFunctionParam, ApiEndpointId, ApplicationBundleData, CollectionName, DatabaseActionType, IntegrationId, QueryName, SchedulerId, ServiceFunctionName, TriggerId, WebhookId } from '@squidcloud/common';
-declare class Meta {
-    data: ApplicationBundleData;
-    /**
-     * @secureDatabase("read", "ExampleIntegration")
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   databases: {
-     *     ExampleIntegration: {
-     *       security: {
-     *         read: ['MyService:myMethod']
-     *       }
-     *     }
-     *   }
-     * }
-     */
-    secureDatabase(type: DatabaseActionType, serviceFunction: ServiceFunctionName, integrationId?: IntegrationId): void;
-    /**
-     * @secureCollection("ExampleCollection", "read", "ExampleIntegration")
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   databases: {
-     *     ExampleIntegration: {
-     *       collections: {
-     *         ExampleCollection: {
-     *           security: {
-     *             read: ['MyService:myMethod']
-     *           }
-     *         }
-     *       }
-     *     }
-     *   }
-     * }
-     */
-    secureCollection(collectionName: CollectionName, type: DatabaseActionType, serviceFunction: ServiceFunctionName, integrationId?: IntegrationId): void;
-    /**
-     * @secureApi("ExampleIntegration", "myEndpoint")
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   apis: {
-     *     ExampleIntegration: {
-     *       myEndpoint: {
-     *         security: ['MyService:myMethod']
-     *       }
-     *     }
-     *   }
-     * }
-     */
-    secureApi(integrationId: IntegrationId, endpointId: ApiEndpointId | undefined, serviceFunction: ServiceFunctionName): void;
-    /**
-     * @secureGraphQL("ExampleIntegration")
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   graphql: {
-     *     ExampleIntegration: {
-     *       security: ['MyService:myMethod']
-     *     }
-     *   }
-     * }
-     */
-    secureGraphQL(integrationId: IntegrationId, serviceFunction: ServiceFunctionName): void;
-    /**
-     * @transformDatabase(""read", "ExampleIntegration")
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   databases: {
-     *     ExampleIntegration: {
-     *       transform: {
-     *         read: {
-     *           type: "read"
-     *           functionName: "MyService:myMethod"
-     *         }
-     *       }
-     *     }
-     *   }
-     * }
-     */
-    transformDatabase(type: DatabaseActionType, serviceFunction: ServiceFunctionName, integrationId?: IntegrationId): void;
-    /**
-     * @transformCollection("ExampleCollection", "read", "ExampleIntegration")
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   databases: {
-     *     ExampleIntegration: {
-     *       collections: {
-     *         ExampleCollection: {
-     *           transform: {
-     *             read: {
-     *               type: "read"
-     *               functionName: "MyService:myMethod"
-     *             }
-     *           }
-     *         }
-     *       }
-     *     }
-     *   }
-     * }
-     */
-    transformCollection(collectionName: CollectionName, type: DatabaseActionType, serviceFunction: ServiceFunctionName, integrationId?: IntegrationId): void;
-    /**
-     * @executable()
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   executables: {
-     *     myExecutable: {
-     *       serviceName: "MyService:myMethod",
-     *     }
-     *   }
-     * }
-     */
-    executable(serviceFunction: ServiceFunctionName): void;
-    /**
-     * @aiFunction()
-     * TODO: update docs
-     * TODO: update all other functions to use Pick<> like we do here
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   aiFunctions: {
-     *     myAiFunction: {
-     *       serviceName: "MyService:myMethod",
-     *     }
-     *   }
-     * }
-     */
-    aiFunction(serviceFunction: ServiceFunctionName, description: string, params: Array<AiFunctionParam>): void;
-    /**
-     * @trigger("my-trigger", "ExampleCollection", "ExampleIntegration")
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   triggers: {
-     *     "my-trigger": {
-     *       integrationId: "ExampleIntegration"
-     *       collectionName: "ExampleCollection"
-     *       functionName: "MyService:myMethod",
-     *     }
-     *   }
-     * }
-     */
-    trigger(id: TriggerId, collectionName: CollectionName, serviceFunction: ServiceFunctionName, integrationId?: IntegrationId): void;
-    /**
-     * @scheduler("my-scheduler", "CronExpression", true)
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   schedulers: {
-     *     "my-scheduler", {
-     *       cronExpression: "CronExpression"
-     *       functionName: "MyService:myMethod",
-     *     }
-     *   }
-     * }
-     */
-    scheduler(id: SchedulerId, cronExpression: string, serviceFunction: ServiceFunctionName, exclusive: boolean): void;
-    /**
-     * @webhook("my-webhook")
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   webhooks: {
-     *     "my-webhook", {
-     *       functionName: "MyService:myMethod",
-     *     }
-     *   }
-     * }
-     */
-    webhook(id: WebhookId, serviceFunction: ServiceFunctionName): void;
-    /**
-     * @namedQuery('exampleIntegration', 'my-query')
-     * static  myQuery = "select * from my-table where id = ${id}";
-     *
-     * Applying the decorator above to the myQuery static string in MyService
-     * class will generate the following metadata:
-     *
-     *
-     *
-     * data: {
-     *   namedQueries: {
-     *     "exampleIntegration", {
-     *       my-query: {
-     *         queryString: "select * from my-table where id = $id"
-     *       }
-     *     }
-     *   }
-     * }
-     */
-    namedQuery(integrationId: IntegrationId, name: QueryName, queryString: string): void;
-    /**
-     * @secureNamedQuery("exampleIntegration", "queryName")
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   namedQueries: {
-     *     exampleIntegration: {
-     *       queryName: {
-     *         security: MyService:myMethod
-     *       }
-     *     }
-     *   }
-     * }
-     */
-    secureNamedQuery(integrationId: IntegrationId, name: QueryName, serviceFunction: ServiceFunctionName): void;
-    secureNativeQuery(integrationId: IntegrationId, serviceFunction: ServiceFunctionName): void;
-    /**
-     * @secureDistributedLock("mutex", true)
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   distributedLocks: {
-     *     security: [MyService:myMethod]
-     *   }
-     * }
-     */
-    secureDistributedLock(mutex: string | undefined, serviceFunction: ServiceFunctionName): void;
-    /**
-     * @secureAiChatbot(ExampleIntegration, "chat", myProfile)
-     *
-     * Applying the decorator above to the myMethod method on the MyService
-     * class will generate the following metadata:
-     *
-     * data: {
-     *   aiChatbots: {
-     *     ExampleIntegration: {
-     *       myProfile: {
-     *         security: {
-     *           chat: ['MyService:myMethod']
-     *         }
-     *       }
-     *     }
-     *   }
-     * }
-     */
-    secureAiChatbot(type: AiChatbotActionType, integrationId: IntegrationId, profileId: string | undefined, serviceFunction: ServiceFunctionName): void;
-    clientConnectionChangeHandler(serviceFunction: ServiceFunctionName): void;
-}
-/**
- * @internal
- */
-export declare const metadata: Meta;
-export {};
+export {};

package/dist/backend/src/metadata.spec.d.ts

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

package/dist/backend/src/project.d.ts

@@ -1,7 +1,12 @@
-/**
- * The SquidProject class is the entry point for the Squid backend project.
- */
-export declare class SquidProject {
-    private metadata;
-    private cleanup;
-}
+import { Squid } from '@squidcloud/client';
+/**
+ * The SquidProject class is the entry point for the Squid backend project.
+ */
+export declare class SquidProject {
+    /**
+     * Initializes lifecycle metadata so the runtime knows which hooks the connector implements.
+     */
+    constructor();
+    /** Returns the main Squid instance with the current backend configuration. */
+    get squid(): Squid;
+}

package/dist/backend/src/public-types.d.ts

@@ -0,0 +1,15 @@
+export * from '../../internal-common/src/public-types-backend/ai-agent.public-context';
+export * from '../../internal-common/src/public-types-backend/api-call.public-context';
+export * from '../../internal-common/src/public-types-backend/application.public-types';
+export * from '../../internal-common/src/public-types-backend/bundle-api.public-types';
+export * from '../../internal-common/src/public-types-backend/bundle-data.public-types';
+export * from '../../internal-common/src/public-types-backend/distributed-lock.public-context';
+export * from '../../internal-common/src/public-types-backend/graphql.public-context';
+export * from '../../internal-common/src/public-types-backend/llm.public-types';
+export * from '../../internal-common/src/public-types-backend/mcp.public-types';
+export * from '../../internal-common/src/public-types-backend/metric.public-context';
+export * from '../../internal-common/src/public-types-backend/mutation.public-context';
+export * from '../../internal-common/src/public-types-backend/native-query.public-context';
+export * from '../../internal-common/src/public-types-backend/query.public-context';
+export * from '../../internal-common/src/public-types-backend/storage.public-types';
+export * from '../../internal-common/src/public-types-backend/topic.public-context';

package/dist/backend/src/squid.service.d.ts

@@ -0,0 +1,143 @@
+import { AiStatusMessage, AuthWithApiKey, AuthWithBearer, ClientId, RunContext, SecretKey, SecretValue, Squid, SquidRegion } from '@squidcloud/client';
+import { SquidFile } from '../../internal-common/src/public-types-backend/bundle-api.public-types';
+import { TenantModuleId } from '../../internal-common/src/public-types-backend/bundle-data.public-types';
+/**
+ * A base class for all the different types of Squid backend services. This class serves as a container
+ * for the various methods implemented in the backend in order to customize the Squid backend for an application.
+ */
+export declare class SquidService {
+    /**
+     * Your application's region. When developing locally, the region will be set to `local`.
+     */
+    readonly region: SquidRegion;
+    readonly backendBaseUrl: string;
+    private readonly config;
+    constructor();
+    /** The list of your application's secrets as defined in the Squid Console. */
+    get secrets(): Record<SecretKey, SecretValue>;
+    /** The list of your application's api keys. */
+    get apiKeys(): Record<SecretKey, string>;
+    /**
+     * The context object for the current request. This object contains information about the current request, such as
+     * the current user, the IP address, the user agent used, the request headers, and more.
+     */
+    get context(): RunContext;
+    /**
+     * Returns the Squid client instance for your application.
+     *
+     * @returns the Squid client instance for your application.
+     */
+    get squid(): Squid;
+    /**
+     * Returns the assets directory for your application.
+     *
+     * @returns the assets directory for your application.
+     */
+    get assetsDirectory(): string;
+    /**
+     * Returns the API key used by the backend for your application.
+     */
+    getApiKey(): string;
+    /**
+     * Returns the auth object for the current request or undefined if unauthenticated or if using an API key.
+     *
+     * @returns The auth object for the current request or undefined if unauthenticated or if using an API key.
+     */
+    getUserAuth(): AuthWithBearer | undefined;
+    /**
+     * Returns the auth object for the current request or undefined if unauthenticated or if using a user token.
+     *
+     * @returns The auth object for the current request or undefined if unauthenticated or if using a user token.
+     */
+    getApiKeyAuth(): AuthWithApiKey | undefined;
+    /**
+     * Returns true if the current request is authenticated (using a user token or an API key).
+     *
+     * @returns true if the current request is authenticated (using a user token or an API key).
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Asserts that the current request is authenticated (using a user token or an API key).
+     * @throws UNAUTHORIZED if the current request is not authenticated.
+     */
+    assertIsAuthenticated(): void;
+    /**
+     * Asserts that the method is called within a valid request scope.
+     * Throws an error if no request context can be found.
+     */
+    assertInRequestScope(): void;
+    /**
+     * Asserts that the current method call includes an API key in the context.
+     * Throws an error if called without an API key.
+     */
+    assertApiKeyCall(): void;
+    /**
+     * A helper method to create a webhook response. This method should be used inside a webhook handler (function
+     * decorated with @webhook).
+     *
+     * @param body The body of the response.
+     * @param statusCode The status code of the response.
+     * @param headers The headers of the response.
+     * @returns The webhook response.
+     */
+    createWebhookResponse(body?: unknown, statusCode?: number, headers?: Record<string, unknown>): any;
+    /**
+     * Throws a webhook response. This function is useful when you want to interrupt normal execution
+     * and immediately return a response from a webhook handler.
+     *
+     * @param content The response content including optional body, status code, and headers.
+     * @throws An object marked as a webhook response.
+     */
+    throwWebhookResponse(content: Partial<{
+        body: unknown;
+        statusCode: number;
+        headers: Record<string, unknown>;
+    }>): never;
+    /**
+     * Constructs a response for an OpenAPI operation. This function is typically used within an OpenAPI handler.
+     *
+     * @param body The payload of the response. If not provided, defaults to an empty string.
+     * @param statusCode The HTTP status code for the response. Defaults to 200 if a body is present, otherwise 204.
+     * @param headers An object containing response headers. Defaults to an empty object if not provided.
+     * @returns The openapi response.
+     */
+    createOpenApiResponse(body?: unknown, statusCode?: number, headers?: Record<string, unknown>): any;
+    /**
+     * Throws an OpenAPI response. This function is useful when you want to interrupt normal execution
+     * and immediately return a response from an OpenAPI handler.
+     *
+     * @param content The response content including optional body, status code, and headers.
+     * @throws An object marked as an OpenAPI response.
+     */
+    throwOpenApiResponse(content: Partial<{
+        body: unknown;
+        statusCode: number;
+        headers: Record<string, unknown>;
+    }>): never;
+    /**
+     * Converts a file to a SquidFile object. This function is useful when you want to return a file using OpenAPI (tsoa
+     * decorators).
+     */
+    convertToSquidFile(file: File): Promise<SquidFile>;
+    /**
+     * Publishes an AI status update to a specific client. Can be used to notify the client about the status of an AI
+     * operation, such as a chat or an aiFunction.
+     */
+    publishAiStatusUpdate(update: AiStatusMessage, clientId: ClientId): Promise<void>;
+}
+/**
+ * Returns a singleton instance of Squid service. Creates the service if needed.
+ * Inherits code bundle info from the caller service: should only be called from the services within the same code
+ * bundle (user code, connector, etc...).
+ * @deprecated: Use `squidInject`.
+ * This method will be removed in the future.
+ */
+export declare function getSquidService<T extends SquidService>(ctor: new () => T, callerService?: unknown): T;
+/**
+ * Returns a singleton instance of Squid service. Creates the service if needed.
+ * This method can only be used after the Squid module is initialized:
+ *  not from the static context when the module is loading.
+ */
+export declare function squidInject<T extends SquidService>(ctor: new () => T, moduleId?: TenantModuleId): T;
+/** Returns the main Squid instance with the current backend configuration. */
+export declare function getSquid(): Squid;

package/dist/backend/src/utils.d.ts

@@ -0,0 +1,3 @@
+import { WebhookResponse } from '../../internal-common/src/public-types-backend/bundle-api.public-types';
+/** Builds a fully defined WebhookResponse using a partial model. */
+export declare function createWebhookResponse(partialResponse: Partial<WebhookResponse>): WebhookResponse;