@squidcloud/backend 1.0.338 → 1.0.339

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

@@ -0,0 +1,94 @@
+/** A type alias for a string that represents a webhook. */
+export type WebhookId = string;
+/** A type alias for a string that represents a trigger id. */
+export type TriggerId = string;
+/** A type alias for a string that represents a scheduler id. */
+export type SchedulerId = string;
+/** The supported cron expression string. */
+export type CronExpressionString = `${string} ${string} ${string} ${string} ${string}` | `${string} ${string} ${string} ${string}`;
+/** A set of predefined cron expressions. */
+export declare enum CronExpression {
+    EVERY_SECOND = "* * * * * *",
+    EVERY_5_SECONDS = "*/5 * * * * *",
+    EVERY_10_SECONDS = "*/10 * * * * *",
+    EVERY_30_SECONDS = "*/30 * * * * *",
+    EVERY_MINUTE = "*/1 * * * *",
+    EVERY_5_MINUTES = "0 */5 * * * *",
+    EVERY_10_MINUTES = "0 */10 * * * *",
+    EVERY_30_MINUTES = "0 */30 * * * *",
+    EVERY_HOUR = "0 0-23/1 * * *",
+    EVERY_2_HOURS = "0 0-23/2 * * *",
+    EVERY_3_HOURS = "0 0-23/3 * * *",
+    EVERY_4_HOURS = "0 0-23/4 * * *",
+    EVERY_5_HOURS = "0 0-23/5 * * *",
+    EVERY_6_HOURS = "0 0-23/6 * * *",
+    EVERY_7_HOURS = "0 0-23/7 * * *",
+    EVERY_8_HOURS = "0 0-23/8 * * *",
+    EVERY_9_HOURS = "0 0-23/9 * * *",
+    EVERY_10_HOURS = "0 0-23/10 * * *",
+    EVERY_11_HOURS = "0 0-23/11 * * *",
+    EVERY_12_HOURS = "0 0-23/12 * * *",
+    EVERY_DAY_AT_1AM = "0 01 * * *",
+    EVERY_DAY_AT_2AM = "0 02 * * *",
+    EVERY_DAY_AT_3AM = "0 03 * * *",
+    EVERY_DAY_AT_4AM = "0 04 * * *",
+    EVERY_DAY_AT_5AM = "0 05 * * *",
+    EVERY_DAY_AT_6AM = "0 06 * * *",
+    EVERY_DAY_AT_7AM = "0 07 * * *",
+    EVERY_DAY_AT_8AM = "0 08 * * *",
+    EVERY_DAY_AT_9AM = "0 09 * * *",
+    EVERY_DAY_AT_10AM = "0 10 * * *",
+    EVERY_DAY_AT_11AM = "0 11 * * *",
+    EVERY_DAY_AT_NOON = "0 12 * * *",
+    EVERY_DAY_AT_1PM = "0 13 * * *",
+    EVERY_DAY_AT_2PM = "0 14 * * *",
+    EVERY_DAY_AT_3PM = "0 15 * * *",
+    EVERY_DAY_AT_4PM = "0 16 * * *",
+    EVERY_DAY_AT_5PM = "0 17 * * *",
+    EVERY_DAY_AT_6PM = "0 18 * * *",
+    EVERY_DAY_AT_7PM = "0 19 * * *",
+    EVERY_DAY_AT_8PM = "0 20 * * *",
+    EVERY_DAY_AT_9PM = "0 21 * * *",
+    EVERY_DAY_AT_10PM = "0 22 * * *",
+    EVERY_DAY_AT_11PM = "0 23 * * *",
+    EVERY_DAY_AT_MIDNIGHT = "0 0 * * *",
+    EVERY_WEEK = "0 0 * * 7",
+    EVERY_WEEKDAY = "0 0 * * 1-5",
+    EVERY_WEEKEND = "0 0 * * 6,7",
+    EVERY_1ST_DAY_OF_MONTH_AT_MIDNIGHT = "0 0 1 * *",
+    EVERY_1ST_DAY_OF_MONTH_AT_NOON = "0 12 1 * *",
+    EVERY_2ND_HOUR = "0 */2 * * *",
+    EVERY_2ND_HOUR_FROM_1AM_THROUGH_11PM = "0 1-23/2 * * *",
+    EVERY_2ND_MONTH = "0 0 1 */2 *",
+    EVERY_QUARTER = "0 0 1 */3 *",
+    EVERY_6_MONTHS = "0 0 1 */6 *",
+    EVERY_YEAR = "0 0 1 1 *",
+    EVERY_30_MINUTES_BETWEEN_9AM_AND_5PM = "0 */30 9-17 * * *",
+    EVERY_30_MINUTES_BETWEEN_9AM_AND_6PM = "0 */30 9-18 * * *",
+    EVERY_30_MINUTES_BETWEEN_10AM_AND_7PM = "0 */30 10-19 * * *",
+    MONDAY_TO_FRIDAY_AT_1AM = "0 0 01 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_2AM = "0 0 02 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_3AM = "0 0 03 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_4AM = "0 0 04 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_5AM = "0 0 05 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_6AM = "0 0 06 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_7AM = "0 0 07 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_8AM = "0 0 08 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_9AM = "0 0 09 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_09_30AM = "0 30 09 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_10AM = "0 0 10 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_11AM = "0 0 11 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_11_30AM = "0 30 11 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_12PM = "0 0 12 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_1PM = "0 0 13 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_2PM = "0 0 14 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_3PM = "0 0 15 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_4PM = "0 0 16 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_5PM = "0 0 17 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_6PM = "0 0 18 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_7PM = "0 0 19 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_8PM = "0 0 20 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_9PM = "0 0 21 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_10PM = "0 0 22 * * 1-5",
+    MONDAY_TO_FRIDAY_AT_11PM = "0 0 23 * * 1-5"
+}

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

@@ -1,30 +1,46 @@
-import { MutationContext } from './mutation.public-context';
+import { MutationContext, MutationType } from './mutation.public-context';
 import { ApiCallContext } from './api-call.public-context';
 import { QueryContext } from './query.public-context';
-import { DatabaseActionType, MetricActionType, StorageActionType, TopicActionType } from '@squidcloud/client';
 import { ClientConnectionState } from '@squidcloud/client';
 import { CollectionName, DocIdOrDocIdObj, DocumentData } from '@squidcloud/client';
-import { MutationType } from '@squidcloud/client';
 import { ClientId, IntegrationId, 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 { AiFunctionContext } from './ai-chatbot.public-context';
-import { StorageContext } from '@squidcloud/client';
 import { NativeQueryContext } from './native-query.public-context';
 import { SecureMetricContext } from './metric.public-context';
-import { SecureAiAgentContext } from '@squidcloud/client';
+import { DatabaseActionType, MetricActionType, StorageActionType, TopicActionType } from './bundle-data.public-types';
+import { StorageContext } from './storage.types';
+import { AiFunctionContext, SecureAiAgentContext } from './ai-agent.public-context';
+/**
+ * @category Database
+ */
 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>);
+/**
+ * @category Storage
+ */
 export type SecureStorageAction<T extends StorageActionType> = T extends 'all' ? () => boolean | Promise<boolean> : (context: StorageContext) => boolean | Promise<boolean>;
+/**
+ * @category Queue
+ */
 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 SecureMetricAction<T extends MetricActionType> = T extends 'all' ? ((context: SecureMetricContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>) : T extends 'write' ? ((context: SecureMetricContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>) : never;
 export type SecureApiAction = ((context: ApiCallContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>);
+/**
+ * @category Database
+ */
 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>);
+/**
+ * @category AI
+ */
 export type SecureAiAgentAction = ((context: SecureAiAgentContext) => boolean | Promise<boolean>) | (() => boolean | Promise<boolean>);
 export type ClientConnectionStateChangeAction = (clientId: ClientId, clientConnectionState: ClientConnectionState) => Promise<void> | void;
 export type ExecutableAction = (...args: any[]) => any;
+/**
+ * @category AI
+ */
 export type AiFunctionAction<T extends Record<string, any> = any> = (params: T, context: AiFunctionContext<any, any>) => any;
 export type TriggerAction = ((request: TriggerRequest) => void | Promise<void>) | (() => void | Promise<void>);
 /** The context provided to a trigger function. */
@@ -39,7 +55,7 @@ export interface TriggerRequest<T extends DocumentData = any> {
     docAfter?: T;
 }
 export type SchedulerAction = () => void | Promise<void>;
-export type LimitedAction = (...args: any[]) => any | Promise<any>;
+export type LimitsAction = (...args: any[]) => any | Promise<any>;
 export type LimiterScope = 'ip' | 'user' | 'global';
 export type QuotaRenewPeriod = 'hourly' | 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'annually';
 /**
@@ -105,4 +121,7 @@ export interface SquidFile {
     size: number;
     encoding?: string;
 }
+/**
+ * Base type for all decorators used in backend projects.
+ */
 export type ActionMethodDecorator<U> = <T extends U>(target: Object, propertyName: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;

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

@@ -0,0 +1,24 @@
+import { IntegrationType } from '@squidcloud/client';
+/** The different types of actions that can be performed on a database. */
+export type DatabaseActionType = 'read' | 'write' | 'update' | 'insert' | 'delete' | 'all';
+/** The different types of actions that can be performed for storage. */
+export type StorageActionType = 'read' | 'write' | 'update' | 'insert' | 'delete' | 'all';
+/** The different types of actions that can be performed on a topic. */
+export type TopicActionType = 'read' | 'write' | 'all';
+/** The different type of actions for metrics. */
+export type MetricActionType = 'write' | 'all';
+export type AiFunctionParamType = 'string' | 'number' | 'boolean' | 'date';
+export interface AiFunctionParam {
+    name: string;
+    description: string;
+    type: AiFunctionParamType;
+    required: boolean;
+}
+/** Additional optional readonly  metadata for AI function. */
+export interface AiFunctionAttributes {
+    /**
+     * Type of integration this function is used for.
+     * Functions with defined 'integrationType' require 'integrationId' to be passed as part of the function context.
+     */
+    integrationType?: Array<IntegrationType>;
+}

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

@@ -1,4 +1,7 @@
-/** A context passed to functions annotated with the '@secureMetric' decorator. */
+/**
+ * A context passed to functions annotated with the '@secureMetric' decorator.
+ * @category Platform
+ */
 export interface SecureMetricContext {
     /** Name of the metric to check. */
     name: string;

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

@@ -1,7 +1,102 @@
 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. */
+import { SquidDocIdObj, SquidDocument } from '@squidcloud/client';
+/**
+ * The mutation type.
+ * @category Database
+ */
+export declare const MUTATION_TYPES: readonly ["insert", "update", "delete"];
+/**
+ * @category Database
+ */
+export type MutationType = (typeof MUTATION_TYPES)[number];
+interface BaseMutation {
+    type: MutationType;
+    squidDocIdObj: SquidDocIdObj;
+}
+/**
+ * A mutation on a document.
+ * @category Database
+ */
+export type Mutation<T = any> = UpdateMutation<T> | InsertMutation<T> | DeleteMutation;
+/**
+ * @category Database
+ */
+export interface DeleteMutation extends BaseMutation {
+    type: 'delete';
+}
+/**
+ * @category Database
+ */
+export interface UpdateMutation<T = any> extends BaseMutation {
+    type: 'update';
+    /** The updated properties */
+    properties: {
+        [key in keyof T & string]?: Array<PropertyMutation<T[key]>>;
+    };
+}
+/**
+ * @category Database
+ */
+export interface InsertMutation<T = any> extends BaseMutation {
+    type: 'insert';
+    /** The inserted document */
+    properties: T;
+}
+/**
+ * A representation of a single property update.
+ * @category Database
+ */
+export type PropertyMutation<Value = any> = ApplyNumericFnPropertyMutation | ApplyStringFnPropertyMutation | ValueUpdatePropertyMutation<Value> | RemovePropertyMutation;
+/**
+ * A value update property mutation.
+ * @category Database
+ */
+export interface ValueUpdatePropertyMutation<Value = any> {
+    type: 'update';
+    value: Value;
+}
+/**
+ * Applying a numeric function to a property.
+ * @category Database
+ */
+export interface ApplyNumericFnPropertyMutation {
+    type: 'applyNumericFn';
+    fn: 'increment';
+    value: number;
+}
+/**
+ * A property update that removes a property from a document.
+ * @category Database
+ */
+export interface RemovePropertyMutation {
+    type: 'removeProperty';
+}
+interface ApplyExtendString {
+    type: 'applyStringFn';
+    fn: 'extendString';
+    value: string;
+}
+interface ApplyTrimString {
+    type: 'applyStringFn';
+    fn: 'trim';
+}
+/**
+ * A property mutation that modifies a string.
+ * @category Database
+ */
+export type ApplyStringFnPropertyMutation = ApplyExtendString | ApplyTrimString;
+/**
+ * The before and after documents of a document change.
+ * @category Database
+ */
+export interface BeforeAndAfterDocs<T = SquidDocument> {
+    before: T | undefined;
+    after: T | undefined;
+}
+/**
+ * The mutation context that will be provided to the security function.
+ * @category Database
+ */
 export declare class MutationContext<T = any> {
     readonly mutation: Mutation<T>;
     readonly beforeAndAfterDocs: BeforeAndAfterDocs<T>;
@@ -22,3 +117,4 @@ export declare class MutationContext<T = any> {
     affectedPaths(startingRoot?: Paths<T> | string): Array<Paths<T>>;
     private checkPath;
 }
+export {};

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

@@ -1,18 +1,30 @@
 import { IntegrationId } from '@squidcloud/client';
+/**
+ * @category Database
+ */
 export type NativeQueryRequestType = 'relational' | 'mongo';
 interface BaseNativeQueryContext {
     type: NativeQueryRequestType;
     integrationId: IntegrationId;
 }
+/**
+ * @category Database
+ */
 export interface RelationalNativeQueryContext extends BaseNativeQueryContext {
     type: 'relational';
     query: string;
     params: Record<string, any>;
 }
+/**
+ * @category Database
+ */
 export interface MongoNativeQueryContext extends BaseNativeQueryContext {
     type: 'mongo';
     collectionName: string;
     aggregationPipeline: Array<any | undefined>;
 }
+/**
+ * @category Database
+ */
 export type NativeQueryContext = RelationalNativeQueryContext | MongoNativeQueryContext;
 export {};

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

@@ -5,6 +5,7 @@ import { IntegrationId } from '@squidcloud/client';
 /**
  * Represents the Squid query context.
  * Passed to methods that require query details, such as those annotated with the `@secureCollection` annotation.
+ * @category Database
  */
 export declare class QueryContext<T extends DocumentData = any> {
     readonly query: Query<T>;
@@ -97,31 +98,58 @@ export declare class QueryContext<T extends DocumentData = any> {
      */
     documentMatchesQuery(doc: DocumentData): boolean;
 }
-/** A list of context conditions */
+/**
+ * A list of context conditions.
+ * @category Database
+ */
 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'. */
+/**
+ * A Context condition - a condition that replaces multiple '==' or '!=' conditions with 'in' and 'not in'.
+ * @category Database
+ */
 export type ContextCondition<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = InContextCondition<Doc, F> | NotInContextCondition<Doc, F> | OtherContextCondition<Doc, F>;
+/**
+ * @category Database
+ */
 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>;
 }
+/**
+ * @category Database
+ */
 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>;
 }
+/**
+ * @category Database
+ */
 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. */
+/**
+ * A condition that includes the 'in' and 'not in' operators.
+ * @category Database
+ */
 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. */
+/**
+ * A list of general conditions.
+ * @category Database
+ */
 export type GeneralConditions<Doc extends DocumentData = any, F extends Paths<Doc> = Paths<Doc>> = Array<GeneralCondition<Doc, F>>;
+/**
+ * @category Database
+ */
 export type ContextOperator = Exclude<Operator, '==' | '!='> | 'in' | 'not in';
 type AllOperators = Operator | 'in' | 'not in';
-/** A generic value that can exist in a query. */
+/**
+ * A generic value that can exist in a query.
+ * @category Database
+ */
 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/storage.types.d.ts

@@ -0,0 +1,9 @@
+import { StorageActionType } from './bundle-data.public-types';
+import { IntegrationId } from '@squidcloud/client';
+export type StorageFunctionality = 'fileUpload' | 'getFileMetadata' | 'getDownloadUrl' | 'deleteFiles' | 'listDirectoryContents';
+export interface StorageContext {
+    integrationId: IntegrationId;
+    pathsInBucket: Array<string>;
+    action: StorageActionType;
+    functionality: StorageFunctionality;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/backend",
-  "version": "1.0.338",
+  "version": "1.0.339",
   "description": "Squid Cloud's backend SDK",
   "main": "dist/index.js",
   "types": "dist/backend/src/index.d.ts",
@@ -11,7 +11,9 @@
     "publish:public": "npm run build && npm publish --access public",
     "build-and-check-public-types": "npm run build && npm run check-public-types",
     "keep-only-public-types": "del-cli 'dist/internal-common/src/**' '!dist/internal-common/src/public-types-backend' '!dist/internal-common/src/public-utils-backend'",
-    "check-public-types": "tsc -p tsconfig.types.json"
+    "check-public-types": "tsc -p tsconfig.types.json",
+    "generate-docs-html": "typedoc",
+    "generate-docs-markdown": "typedoc --plugin typedoc-plugin-markdown --readme none --out ./generated-docs/markdown"
   },
   "files": [
     "dist/**/*"
@@ -23,10 +25,15 @@
     "assertic": "^1.2.1",
     "lodash": "^4.17.21",
     "tsoa": "^6.3.0",
-    "graphql": "^16.9.0"
+    "graphql": "^16.9.0",
+    "otrie": "^1.1.3"
+  },
+  "devDependencies": {
+    "typedoc": "^0.28.0",
+    "typedoc-plugin-markdown": "^4.5.2"
   },
   "peerDependencies": {
-    "@squidcloud/client": "^1.0.338"
+    "@squidcloud/client": "^1.0.339"
   },
   "engines": {
     "node": ">=20.0.0"