@squidcloud/backend 1.0.210 → 1.0.212

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

@@ -6,4 +6,5 @@ export * from '../../internal-common/src/public-types-backend/graphql.public-con
 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/service.public-types';
 export * from '../../internal-common/src/public-types-backend/topic.public-context';

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

@@ -1,4 +1,5 @@
 import { AuthWithApiKey, AuthWithBearer, RunContext, SecretKey, SecretValue, Squid, SquidRegion } from '@squidcloud/client';
+import { ServiceGlobalConfig } from '../../internal-common/src/public-types-backend/service.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.
@@ -9,6 +10,7 @@ export declare class SquidService {
      * Your application's region. When developing locally, the region will be set to `local`.
      */
     readonly region: SquidRegion;
+    constructor(config: ServiceGlobalConfig);
     /** The list of your application's secrets as defined in the Squid Cloud Console. */
     get secrets(): Record<SecretKey, SecretValue>;
     /**

package/dist/index.js.LICENSE.txt

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Lodash <https://lodash.com/>
+ * Copyright OpenJS Foundation and other contributors <https://openjsf.org/>
+ * Released under MIT license <https://lodash.com/license>
+ * Based on Underscore.js 1.8.3 <http://underscorejs.org/LICENSE>
+ * Copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors
+ */

package/dist/internal-common/src/public-types-backend/ai-chatbot.public-context.d.ts

@@ -0,0 +1,27 @@
+import { AiChatbotMutationType, AiChatbotResourceType } from '@squidcloud/client';
+export type AiChatbotContextType = 'text' | 'url' | 'file';
+export interface AiChatbotContextBase {
+    type: AiChatbotContextType;
+    data: string;
+}
+export interface AiChatbotTextContext extends AiChatbotContextBase {
+    type: 'text';
+}
+export interface AiChatbotUrlContext extends AiChatbotContextBase {
+    type: 'url';
+}
+export interface AiChatbotFileContext extends AiChatbotContextBase {
+    type: 'file';
+}
+export declare class AiChatbotChatContext {
+    readonly prompt: string;
+    readonly profileId: string;
+}
+/** A context provided to the security rules of an AI Chatbot mutation. */
+export declare class AiChatbotMutationContext {
+    readonly type: AiChatbotMutationType;
+    readonly resource: AiChatbotResourceType;
+    readonly profileId: string;
+    readonly payload: any;
+}
+export type AiChatbotContext = AiChatbotTextContext | AiChatbotUrlContext | AiChatbotFileContext;

package/dist/internal-common/src/public-types-backend/api-call.public-context.d.ts

@@ -0,0 +1,25 @@
+import { ApiEndpointId, HttpMethod } from '@squidcloud/client';
+import { IntegrationId } from '@squidcloud/client';
+/** The headers of an API call. */
+export type ApiHeaders = Record<string, string | number | boolean>;
+/** The context of an API call. */
+export declare class ApiCallContext {
+    readonly integrationId: IntegrationId;
+    readonly endpointId: ApiEndpointId;
+    readonly url: string;
+    readonly method: HttpMethod;
+    readonly body: unknown;
+    readonly options: ApiOptions;
+}
+export interface ApiOptions {
+    headers?: Record<string, string | number | boolean>;
+    queryParams?: Record<string, string | number | boolean>;
+    pathParams?: Record<string, string | number | boolean>;
+}
+export interface CallApiRequest<BodyType = any> {
+    integrationId: IntegrationId;
+    endpointId: ApiEndpointId;
+    body?: BodyType;
+    overrideMethod?: HttpMethod;
+    options: ApiOptions;
+}

package/dist/internal-common/src/public-types-backend/bundle-api.public-types.d.ts

@@ -0,0 +1,101 @@
+import { MutationContext } from './mutation.public-context';
+import { ApiCallContext } from './api-call.public-context';
+import { QueryContext } from './query.public-context';
+import { AiChatbotActionType, DatabaseActionType, StorageActionType, TopicActionType } from '@squidcloud/client';
+import { ClientConnectionState } from '@squidcloud/client';
+import { DocumentData } from '@squidcloud/client';
+import { MutationType } from '@squidcloud/client';
+import { ClientId, SquidDocId } from '@squidcloud/client';
+import { TopicReadContext, TopicWriteContext } from './topic.public-context';
+import { DistributedLockContext } from './distributed-lock.public-context';
+import { GraphqlContext } from './graphql.public-context';
+import { AiChatbotChatContext, AiChatbotMutationContext } from './ai-chatbot.public-context';
+import { StorageContext } from '@squidcloud/client';
+import { NativeQueryContext } from './native-query.public-context';
+export type SecureDatabaseAction<T extends DatabaseActionType> = T extends 'all' ? () => boolean | Promise<boolean> : T extends 'read' ? ((context: QueryContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>) : ((context: MutationContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>);
+export type SecureStorageAction<T extends StorageActionType> = T extends 'all' ? () => boolean | Promise<boolean> : (context: StorageContext) => boolean | Promise<boolean>;
+export type SecureTopicAction<T extends TopicActionType> = T extends 'all' ? () => boolean | Promise<boolean> : T extends 'read' ? ((context: TopicReadContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>) : ((context: TopicWriteContext<T>) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>);
+export type SecureApiAction = ((context: ApiCallContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>);
+export type SecureNativeQueryAction = ((context: NativeQueryContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>);
+export type SecureDistributedLockAction = ((context: DistributedLockContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>);
+export type SecureGraphQLAction = ((context: GraphqlContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>);
+export type SecureAiChatbotAction<T extends AiChatbotActionType> = T extends 'all' ? () => boolean | Promise<boolean> : T extends 'chat' ? ((context: AiChatbotChatContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>) : ((context: AiChatbotMutationContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>);
+export type ClientConnectionStateChangeAction = (clientId: ClientId, clientConnectionState: ClientConnectionState) => Promise<void> | void;
+export type ExecutableAction = (...args: any[]) => any;
+export type AiFunctionAction<T extends Record<string, any> = any> = (params: T) => any;
+export type TriggerAction = ((request: TriggerRequest) => void | Promise<void>) | (() => void | Promise<void>);
+/** The context provided to a trigger function. */
+export interface TriggerRequest<T extends DocumentData = any> {
+    squidDocId: SquidDocId;
+    mutationType: MutationType;
+    docBefore?: T;
+    docAfter?: T;
+}
+export type SchedulerAction = () => void | Promise<void>;
+export type LimitedAction = () => any | Promise<any>;
+export type LimiterScope = 'ip' | 'user' | 'global';
+export type QuotaRenewPeriod = 'hourly' | 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'annually';
+/**
+ * Options for rate limiting.
+ *
+ * @param value Number of executions permitted per second. Note that we
+ *              permit bursts of up to 3x the specified limit.
+ *  @param scope What this limit applies to: per user? per IP? global?
+ */
+export interface RateLimitOptions {
+    value: number;
+    scope?: LimiterScope;
+}
+/**
+ * Options for quota limiting.
+ *
+ * @param value Number of total executions allowed. Note that this would be
+ *              reset upon any redeployment of the backend.
+ *  @param scope What this limit applies to: per user? per IP? global?
+ */
+export interface QuotaLimitOptions {
+    value: number;
+    scope?: LimiterScope;
+    renewPeriod?: QuotaRenewPeriod;
+}
+/**
+ * Options for rate and quota limiting backend functions.
+ *
+ * This mirrors the type in Kotlin. It is not the type the developer defines in their code, which is LimiterConfig.
+ *
+ * @param rateLimit RateLimitOptions configurations. Allows for different limits at different scopes.
+ * @param quotaLimit QuotaLimitOptions configurations. Allows for different limits at different scopes.
+ */
+export interface LimiterOptions {
+    rateLimit?: RateLimitOptions[];
+    quotaLimit?: QuotaLimitOptions[];
+}
+export type LimiterConfig = {
+    rateLimit?: number | RateLimitOptions | Array<RateLimitOptions>;
+    quotaLimit?: number | QuotaLimitOptions | Array<QuotaLimitOptions>;
+};
+export type WebhookAction = ((request: WebhookRequest) => any) | (() => any);
+/** The context provided to a webhook function. */
+export interface WebhookRequest<T = any> {
+    body: T;
+    rawBody?: string;
+    queryParams: Record<string, string>;
+    headers: Record<string, string>;
+    httpMethod: 'post' | 'get' | 'put' | 'delete';
+    files?: Array<SquidFile>;
+}
+export interface WebhookResponse {
+    headers: Record<string, any>;
+    body: any;
+    statusCode: number;
+    __isWebhookResponse__: true;
+}
+export interface SquidFile {
+    data: Uint8Array;
+    fieldName: string;
+    mimetype: string;
+    originalName: string;
+    size: number;
+    encoding?: string;
+}
+export type ActionMethodDecorator<U> = <T extends U>(target: Object, propertyName: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;

package/dist/internal-common/src/public-types-backend/distributed-lock.public-context.d.ts

@@ -0,0 +1,4 @@
+/** The context provided to a secure distributed lock function. */
+export declare class DistributedLockContext {
+    readonly mutex: string;
+}

package/dist/internal-common/src/public-types-backend/graphql.public-context.d.ts

@@ -0,0 +1,7 @@
+/** The context provided to a secure GraphQL function. */
+export declare class GraphqlContext {
+    readonly isGraphiQL: boolean;
+    readonly query: string | undefined;
+    readonly variables: string | Record<string, any> | undefined;
+    readonly operationName: string | undefined;
+}

package/dist/internal-common/src/public-types-backend/mutation.public-context.d.ts

@@ -0,0 +1,14 @@
+import { Paths } from '@squidcloud/client';
+import { BeforeAndAfterDocs } from '@squidcloud/client';
+import { Mutation, MutationType } from '@squidcloud/client';
+/** The mutation context that will be provided to the security function. */
+export declare class MutationContext<T = any> {
+    readonly mutation: Mutation<T>;
+    readonly beforeAndAfterDocs: BeforeAndAfterDocs<T>;
+    readonly serverTimeStamp: Date;
+    getMutationType(): MutationType;
+    get before(): T | undefined;
+    get after(): T | undefined;
+    /** Returns true if the mutation affects the provided path. */
+    affectsPath(path: Paths<T>): boolean;
+}

package/dist/internal-common/src/public-types-backend/native-query.public-context.d.ts

@@ -0,0 +1,18 @@
+import { IntegrationId } from '@squidcloud/client';
+export type NativeQueryRequestType = 'relational' | 'mongo';
+interface BaseNativeQueryRequest {
+    type: NativeQueryRequestType;
+    integrationId: IntegrationId;
+}
+export interface RelationalNativeQueryRequest extends BaseNativeQueryRequest {
+    type: 'relational';
+    query: string;
+    params: Record<string, any>;
+}
+export interface MongoNativeQueryRequest extends BaseNativeQueryRequest {
+    type: 'mongo';
+    collectionName: string;
+    aggregationPipeline: Array<any | undefined>;
+}
+export type NativeQueryContext = RelationalNativeQueryRequest | MongoNativeQueryRequest;
+export {};

package/dist/internal-common/src/public-types-backend/query.public-context.d.ts

@@ -0,0 +1,123 @@
+import { FieldSort, Operator, Query, SimpleCondition } from '@squidcloud/client';
+import { DeepRecord, FieldOf, PartialBy, Paths } from '@squidcloud/client';
+import { CollectionName, DocumentData } from '@squidcloud/client';
+import { IntegrationId } from '@squidcloud/client';
+export declare class QueryContext<T extends DocumentData = any> {
+    readonly query: Query<T>;
+    /**
+     * The ID of the integration being queried.
+     */
+    get integrationId(): IntegrationId;
+    /**
+     * The name of the collection being queried.
+     */
+    get collectionName(): CollectionName;
+    /**
+     * The query limit if one exists, -1 otherwise.
+     */
+    get limit(): number;
+    /**
+     * Verifies that the query's sort order aligns with the provided field sorts. The fields specified in the `sorts`
+     * parameter must appear in the exact order at the beginning of the query's sort sequence. The query can include
+     * additional fields in its sort order, but only after the specified sorts.
+     *
+     * @param sorts An array of field sorts.
+     * @returns Whether the query's sorts matches the provided field sorts.
+     */
+    sortedBy(sorts: Array<PartialBy<FieldSort<T>, 'asc'>>): boolean;
+    /**
+     * Verifies that the query's sort order exactly matches the provided field sorts. The fields specified in the
+     * `sorts` parameter must appear in the exact order in the query's sort sequence. No additional sorts may be present
+     * in the query.
+     *
+     * @param sorts An array of field sorts.
+     * @returns Whether the query's sorts exactly match the provided field sorts.
+     */
+    sortedByExact(sorts: Array<PartialBy<FieldSort<T>, 'asc'>>): boolean;
+    /**
+     * Verifies that the query is a subquery of the specified condition. A subquery is defined as a query that evaluates
+     * to a subset of the results that would be obtained by applying the parent condition. The subquery may also include
+     * additional conditions, as these only narrow the result set.
+     *
+     * @param fieldName The name of the field for the condition.
+     * @param operator The operator of the condition.
+     * @param value The value of the condition.
+     * @returns Whether the query is a subquery of the parent condition.
+     */
+    isSubqueryOf<F extends Paths<T>, O extends AllOperators>(fieldName: F, operator: O, value: GenericValue<T, F, O> | null): boolean;
+    /**
+     * Verifies that the query is a subquery of the specified condition. A subquery is defined as a query that evaluates
+     * to a subset of the results that would be obtained by applying the parent condition. The subquery may also include
+     * additional conditions, as these only narrow the result set.
+     *
+     * @param condition The condition to validate.
+     * @returns Whether the query is a subquery of the parent condition.
+     */
+    isSubqueryOfCondition(condition: GeneralCondition<T>): boolean;
+    /**
+     * Verifies that the query is a subquery of the specified conditions. A subquery is defined as a query that evaluates
+     * to a subset of the results that would be obtained by applying the parent conditions. The subquery may also include
+     * additional conditions, as these only narrow the result set.
+     *
+     * @param conditions The conditions to validate.
+     * @returns Whether the query includes subquery of the parent conditions.
+     */
+    isSubqueryOfConditions(conditions: GeneralConditions<T>): boolean;
+    /**
+     * Verifies that the query is a subquery of the specified query. A subquery is defined as a query that evaluates
+     * to a subset of the results that obtained for the parent query, including sorts and limits.
+     *
+     * @param query The query to validate.
+     * @returns Whether the query is a subquery of the parent query.
+     */
+    isSubqueryOfQuery(query: Query<T>): boolean;
+    /**
+     * Returns all conditions that apply to any of the specified field names. This method
+     * provides a convenient way to retrieve all conditions that involve a specific set of fields.
+     *
+     * @param fieldNames The field names for which to retrieve conditions.
+     * @returns An array of conditions that involve any of the specified field names.
+     */
+    getConditionsFor<K extends Paths<T>>(...fieldNames: Array<K>): ContextConditions<T, K>;
+    /**
+     * Returns all conditions that apply to the specified field name. This method provides
+     * a convenient way to retrieve all conditions that involve a specific field.
+     *
+     * @param fieldName The field name for which to retrieve conditions.
+     * @returns An array of conditions that involve the specified field name.
+     */
+    getConditionsForField<K extends Paths<T>>(fieldName: K): ContextConditions<T>;
+    /**
+     * Returns true if the given document can be a result of the query.
+     * The method does not account for limit and sort order.
+     */
+    documentMatchesQuery(doc: DocumentData): boolean;
+}
+/** A list of context conditions */
+export type ContextConditions<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = Array<ContextCondition<Doc, F>>;
+/** A Context condition - a condition that replaces multiple '==' or '!=' conditions with 'in' and 'not in'. */
+export type ContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = InContextCondition<Doc, F> | NotInContextCondition<Doc, F> | OtherContextCondition<Doc, F>;
+export interface InContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, 'in'> {
+    operator: 'in';
+    value: Array<FieldOf<DeepRecord<Doc>, Paths<Doc>> | any>;
+}
+export interface NotInContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, 'not in'> {
+    operator: 'not in';
+    value: Array<FieldOf<DeepRecord<Doc>, Paths<Doc>> | any>;
+}
+export interface OtherContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, Exclude<ContextOperator, 'in' | 'not in'>> {
+    operator: Exclude<ContextOperator, 'in' | 'not in'>;
+    value: FieldOf<DeepRecord<Doc>, Paths<Doc>> | any;
+}
+/** A condition that includes the 'in' and 'not in' operators. */
+export interface GeneralCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> extends SimpleCondition<Doc, F, AllOperators> {
+    operator: AllOperators;
+    value: any;
+}
+/** A list of general conditions. */
+export type GeneralConditions<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = Array<GeneralCondition<Doc, F>>;
+export type ContextOperator = Exclude<Operator, '==' | '!='> | 'in' | 'not in';
+type AllOperators = Operator | 'in' | 'not in';
+/** A generic value that can exist in a query. */
+export type GenericValue<Doc = any, F extends Paths<Doc> = Paths<Doc>, O extends AllOperators = any> = O extends 'in' ? Array<DeepRecord<Doc>[F]> | null : O extends 'not in' ? Array<DeepRecord<Doc>[F]> | null : DeepRecord<Doc>[F] | null;
+export {};

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

@@ -0,0 +1,29 @@
+/// <reference types="node" />
+import { AsyncLocalStorage } from 'async_hooks';
+import { AppId, EnvironmentId, SquidDeveloperId } from '@squidcloud/client';
+import { Auth, RunContext } from '@squidcloud/client';
+import { SecretKey } from '@squidcloud/client';
+/**
+ * Immutable part of the service config: this part of the Service config never changes for a service.
+ */
+export interface ServiceGlobalConfig {
+    codeDir: string;
+    environmentId?: EnvironmentId;
+    /** Your applicationId. */
+    appId: AppId;
+    squidDeveloperId?: SquidDeveloperId;
+    backendApiKey: string;
+    /**
+     * Current states of the secrets.
+     * Mutable, and can be dynamically updated in runtime.
+     */
+    secrets: Record<SecretKey, any>;
+    requestLocalStorage: AsyncLocalStorage<ServiceRequestConfig>;
+}
+/**
+ * The part of the service config that changes every request.
+ */
+export interface ServiceRequestConfig {
+    auth: Auth | undefined;
+    context: RunContext;
+}

package/dist/internal-common/src/public-types-backend/topic.public-context.d.ts

@@ -0,0 +1,10 @@
+import { IntegrationId } from '@squidcloud/client';
+export interface TopicReadContext {
+    integrationId: IntegrationId;
+    topicName: string;
+}
+export interface TopicWriteContext<T> {
+    integrationId: IntegrationId;
+    topicName: string;
+    messages: Array<T>;
+}