@tellescope/schema 0.0.7 → 0.0.8

package/src/schema.ts

@@ -1,7 +1,29 @@
-import "@tellescope/types"
-// import "@tellescope/types-server"
+import {
+  ServerModelForName,
+  DatabaseModel,
+  DatabaseRecord,
+  Enduser,
+  ObjectId,
+  ModelName,
+} from "@tellescope/types-server"
+import {
+  ErrorInfo,
+  Indexable,
+  Operation,
+  JSONType,
+  CRUD,
+  HTTPMethod,
+} from "@tellescope/types-utilities"
+import {
+  EnduserSession,
+  ConfiguredSession,
+  JourneyState,
+  UserSession,
+} from "@tellescope/types-models"
 
 import {
+  EscapeBuilder,
+
   booleanValidator,
   dateValidator,
   emailValidator,
@@ -33,6 +55,8 @@ import {
   stringValidator250,
   stringValidator5000,
   listOfDisplayNameInfo,
+  fileTypeValidator,
+  fileSizeValidator,
 } from "@tellescope/validation"
 
 import {
@@ -40,123 +64,126 @@ import {
   DEFAULT_OPERATIONS,
   PLACEHOLDER_ID,
 } from "@tellescope/constants"
+export type RelationshipConstraint<T> = {
+  explanation: string; // human readable, for documentation purposes
+  evaluate: (v: T, dependencies: Indexable<Partial<DatabaseModel>>) => string | void;
+}
+
+export type DependencyAccessConstraint <T> = { type: 'dependency', foreignModel: ModelName, foreignField: string, accessField: keyof T  }
+
+export type AccessConstraint <T> = { type: 'creatorOnly' } 
+  | { type: 'filter', field: string }
+  | DependencyAccessConstraint<T>
+
+export type UniqueArrayConstraint <T> = { array: keyof T, itemKey?: string }
+
+export type Constraint <T> = {
+  unique: (keyof T & string | UniqueArrayConstraint<T>)[];
+  globalUnique?: (keyof T)[];
+  relationship: RelationshipConstraint<Partial<T>>[];
+  access?: AccessConstraint<T>[];
+}
+
+export type Initializer <T, R> = (a: T, s: ConfiguredSession | EnduserSession) => R
+
+export type EndpointOptions = {
+  // parameters used for endpoint that aren't stored in the model
+  parameters?: { [index: string]: EscapeBuilder<any> }, 
+}
+
+export type DependencyDeletionAction = 'delete' | 'unset' | 'setNull' | 'nop'
+export type DependecyRelationship = 'foreignKey' | 'value'
+
+export type Dependency <T=DatabaseRecord> = {
+  dependsOn: ModelName[], // list of => OR, multiple dependency records => AND
+  dependencyField: string,
+  relationship: DependecyRelationship,
+  onDependencyDelete: DependencyDeletionAction,
+  getDependentValues?: (t: T) => JSONType[], // for accessing the values of a Dependency 
+  filterByDependency?: (foreignValue: JSONType, foreignModel?: DatabaseModel) => { // for filtering against a Dependency
+    field: string,
+    value: JSONType | 'any',
+  },
+}
+
+export type ModelFieldInfo <T, R> = {
+  validator: EscapeBuilder<R>,
+  readonly?:  boolean,
+  required?:  boolean,
+  updatesDisabled?: boolean,
+  examples?:  JSONType[],
+  initializer?: Initializer<Partial<T>, R>, // should include the required fields of T, not just partial
+  dependencies?: Dependency<Partial<T>>[],
+}
+
+export type ModelFields<T> = {
+  [K in keyof T]: ModelFieldInfo<T, T[K]>
+}
+export type extractFields<Type> = Type extends ModelFields<infer X> ? X : never
+
+type ArgumentInfo = {
+  description?: string;
+}
+
+type ActionInfo = {
+  name?: string,
+  description?: string,
+  notes?: string[],
+  warnings?: string[],
+}
+
+type CustomAction <P=any, R=any> = {
+  op: Operation | 'custom',
+  access: CRUD,
+  // parameters: InputValidation<P>,
+  parameters: ModelFields<P>,
+  returns: R extends Array<any> ? ModelFieldInfo<any, R> : ModelFields<R>,
+  path?: string,
+  method?: HTTPMethod,
+  enduserOnly?: boolean,
+} & ActionInfo
+
+export type EnduserAction = {
+  field?: string,
+} & ActionInfo
+
+type CustomActionsForModel = {
+  [K in ModelName]: { [index: string]: CustomAction }
+}
+
+type ReadFilter <T> = { [K in keyof T]?: { required: boolean } }
 
-// type RelationshipConstraint<T> = {
-//   explanation: string; // human readable, for documentation purposes
-//   evaluate: (v: T, dependencies: Indexable<Partial<DatabaseModel>>) => string | void;
-// }
-
-// type DependencyAccessConstraint <T> = { type: 'dependency', foreignModel: ModelName, foreignField: string, accessField: keyof T  }
-
-// type AccessConstraint <T> = { type: 'creatorOnly' } 
-//   | { type: 'filter', field: string }
-//   | DependencyAccessConstraint<T>
-
-// type UniqueArrayConstraint <T> = { array: keyof T, itemKey?: string }
-
-// type Constraint <T> = {
-//   unique: (keyof T & string | UniqueArrayConstraint<T>)[];
-//   globalUnique?: (keyof T)[];
-//   relationship: RelationshipConstraint<Partial<T>>[];
-//   access?: AccessConstraint<T>[];
-// }
-
-// type Initializer <T, R> = (a: T, s: ConfiguredSession) => R
-
-// type EndpointOptions = {
-//   // parameters used for endpoint that aren't stored in the model
-//   parameters?: { [index: string]: EscapeBuilder<any> }, 
-// }
-
-// type DependencyDeletionAction = 'delete' | 'unset' | 'setNull' | 'nop'
-// type DependecyRelationship = 'foreignKey' | 'value'
-
-// type Dependency <T=DatabaseRecord> = {
-//   dependsOn: ModelName[], // list of => OR, multiple dependency records => AND
-//   dependencyField: string,
-//   relationship: DependecyRelationship,
-//   onDependencyDelete: DependencyDeletionAction,
-//   getDependentValues?: (t: T) => JSONType[], // for accessing the values of a Dependency 
-//   filterByDependency?: (foreignValue: JSONType, foreignModel?: DatabaseModel) => { // for filtering against a Dependency
-//     field: string,
-//     value: JSONType | 'any',
-//   },
-// }
-
-// type ModelFieldInfo <T, R> = {
-//   validator: EscapeBuilder<R>,
-//   readonly?:  boolean,
-//   required?:  boolean,
-//   updatesDisabled?: boolean,
-//   examples?:  JSONType[],
-//   initializer?: Initializer<Partial<T>, R>, // should include the required fields of T, not just partial
-//   dependencies?: Dependency<Partial<T>>[],
-// }
-
-// export type ModelFields<T> = {
-//   [K in keyof T]: ModelFieldInfo<T, T[K]>
-// }
-// type extractFields<Type> = Type extends ModelFields<infer X> ? X : never
-
-// type ArgumentInfo = {
-//   description?: string;
-// }
-
-// type ActionInfo = {
-//   name?: string,
-//   description?: string,
-//   notes?: string[],
-//   warnings?: string[],
-// }
-
-// type CustomAction <P=any, R=any> = {
-//   op: Operation | 'custom',
-//   access: CRUD,
-//   // parameters: InputValidation<P>,
-//   parameters: ModelFields<P>,
-//   returns: ModelFields<R>,
-//   path?: string,
-//   method?: HTTPMethod,
-// } & ActionInfo
-
-// type CustomActionsForModel = {
-//   [K in ModelName]: { [index: string]: CustomAction }
-// }
-
-// type ReadFilter <T> = { [K in keyof T]?: { required: boolean } }
-
-
-// // m is the original model (or undefined, if create)
-// // allows for easier event handling based on specific updates (by comparing args to pre-update model)
-// type SideEffectHandler <T, O=any> = (args: Partial<T>[], m: (Partial<T> | undefined)[] | undefined, n: (Partial<T> & { _id: ObjectId })[], s: ConfiguredSession, o: O) => Promise<ErrorInfo[]>;
-
-// type SideEffect = {
-//   name: string;
-//   description: string;
-// }
-
-// export type Model<T, N extends ModelName> = {
-//   info: { 
-//     name?: string, 
-//     description?: string, 
-//     sideEffects?: { [K in Operation]?: SideEffect[] }
-//   },
-//   fields: ModelFields<T>,
-//   constraints: Constraint<T>,
-//   defaultActions: { [K in Operation]?: ActionInfo },
-//   customActions: CustomActionsForModel[N],
-//   readFilter?: ReadFilter<T>,
-//   options?: {
-//     create?: EndpointOptions,
-//   }
-// }
-// type extractModelType<Type> = Type extends Model<infer T, infer N> ? T : never
-
-// type DatabaseModelForName = ToServerModels<ModelForName>
-
-// type Schema = {
-//   [N in keyof DatabaseModelForName]: Model<DatabaseModelForName[N], ModelName>
-// }
+
+// m is the original model (or undefined, if create)
+// allows for easier event handling based on specific updates (by comparing args to pre-update model)
+export type SideEffectHandler <T, O=any> = (args: Partial<T>[], m: (Partial<T> | undefined)[] | undefined, n: (Partial<T> & { _id: ObjectId })[], s: ConfiguredSession | EnduserSession, o: O) => Promise<ErrorInfo[]>;
+
+type SideEffect = {
+  name: string;
+  description: string;
+}
+
+export type Model<T, N extends ModelName> = {
+  info: { 
+    name?: string, 
+    description?: string, 
+    sideEffects?: { [K in Operation]?: SideEffect[] }
+  },
+  fields: ModelFields<T>,
+  constraints: Constraint<T>,
+  defaultActions: { [k in Operation]?: ActionInfo },
+  enduserActions?: { [index: string]: EnduserAction },
+  customActions: CustomActionsForModel[N],
+  readFilter?: ReadFilter<T>,
+  options?: {
+    create?: EndpointOptions,
+  }
+}
+export type extractModelType<Type> = Type extends Model<infer T, infer N> ? T : never
+
+export type Schema = {
+  [N in keyof ServerModelForName]: Model<ServerModelForName[N], ModelName>
+}
 
 const sideEffects = {
   trackJourneyEngagement: {
@@ -203,7 +230,11 @@ export type BuiltInFields_T = typeof BuiltInFields
 export type CustomActions = {
   api_keys: {
     create: CustomAction<{}, { id: string, key: string}>,
-  }
+  },
+  files: {
+    prepare_file_upload: CustomAction<{ name: string, size: number, type: string }, { presignedUpload: object, file: File }>,
+    file_download_URL: CustomAction<{ secureName: string }, { downloadURL: string }>,
+  },
   journeys: {
     update_state: CustomAction<{ updates: JourneyState, id: string, name: string }, {}>,
   },
@@ -246,72 +277,26 @@ export const schema: SchemaV1 = {
         update: [sideEffects.trackJourneyEngagement],
       }
     },
-    customActions: {
-      set_password: {
-        op: "custom", access: 'update', method: "post",
-        name: 'Set enduser password',
-        path: '/set-enduser-password',
-        description: "Sets (or resets) an enduser's password. Minimum length 8 characters.",
-        parameters: { 
-          id: { validator: mongoIdStringValidator, required: true },
-          password: { validator: stringValidator100, required: true },
-        },
-        returns: { } //authToken: { validator: stringValidator5000 } },
-      },
-      is_authenticated: {
-        op: "custom", access: 'read', method: "get",
-        name: 'Check enduser authentication',
-        path: '/enduser-is-authenticated',
-        description: "Checks the validity of an enduser's authToken",
-        parameters: { 
-          id: { validator: mongoIdStringValidator, required: true },
-          authToken: { validator: stringValidator5000, required: true },
-        },
-        returns: { 
-          isAuthenticated: { validator: booleanValidator, required: true }, 
-          enduser: { validator:  'enduser' }, 
-        } as any // add enduser eventually, when validator defined
-      },
-      refresh_session: {
-        op: "custom", access: 'update', method: "post",
-        name: 'Refresh enduser authentication',
-        path: '/refresh-enduser-session',
-        description: "When called by an authenticated enduser, generates a new session",
-        parameters: { },
-        enduserOnly: true,
-        returns: { 
-          authToken: { validator: stringValidator, required: true }, 
-          enduser: { validator:  'enduser' }, 
-        } as any // add enduser eventually, when validator defined
-      },
-      logout: {
-        op: "custom", access: 'update', method: "post",
-        name: 'Logout enduser',
-        path: '/logout-enduser',
-        description: "Logs out an enduser",
-        parameters: {},
-        returns: {},
-      },
+    constraints: {
+      unique: ['email', 'phone', 'externalId'],
+      relationship: [
+        {
+          explanation: 'One of email or phone is required',
+          evaluate: ({ email, phone }) => {
+          if (!(email || phone))
+            return 'One of email or phone is required'
+          } 
+        }
+      ],
     },
+    defaultActions: DEFAULT_OPERATIONS,
     enduserActions: { logout: {}, refresh_session: {} },
-    publicActions: {
-      login: {
-        op: "custom", access: 'read', method: "post",
-        name: 'Login enduser',
-        path: '/login-enduser',
-        description: "Generates an authentication token for access to enduser-facing endpoints",
-        enduserOnly: true, // implemented as authenticate in enduser sdk only
-        parameters: { 
-          id: { validator: mongoIdStringValidator },
-          password: { validator: stringValidator100, required: true }, // required until optional challenge token available
-          phone: { validator: phoneValidator },
-          email: { validator: emailValidator },
-        },
-        returns: { authToken: { validator: stringValidator5000 } },
-      },
-    },
     fields: {
       ...BuiltInFields,   
+      externalId: {
+        validator: stringValidator250,
+        examples: ['addfed3e-ddea-415b-b52b-df820c944dbb'],
+      },
       email: { 
         validator: emailValidator,
         examples: ['test@tellescope.com'],
@@ -374,23 +359,84 @@ export const schema: SchemaV1 = {
       lastCommunication: { 
         validator: dateValidator,
       },
+      avatar: {
+        validator: stringValidator100,
+        dependencies: [
+          {
+            dependsOn: ['files'],
+            dependencyField: 'secureName',
+            relationship: 'foreignKey',
+            onDependencyDelete: 'unset',
+          },
+        ]
+      },
       // recentMessagePreview: { 
       //   validator: stringValidator,
       // },
     }, 
-    constraints: {
-      unique: ['email', 'phone'],
-      relationship: [
-        {
-          explanation: 'One of email or phone is required',
-          evaluate: ({ email, phone }) => {
-          if (!(email || phone))
-            return 'One of email or phone is required'
-          } 
-        }
-      ],
+    customActions: {
+      set_password: {
+        op: "custom", access: 'update', method: "post",
+        name: 'Set enduser password',
+        path: '/set-enduser-password',
+        description: "Sets (or resets) an enduser's password. Minimum length 8 characters.",
+        parameters: { 
+          id: { validator: mongoIdStringValidator, required: true },
+          password: { validator: stringValidator100, required: true },
+        },
+        returns: { } //authToken: { validator: stringValidator5000 } },
+      },
+      is_authenticated: {
+        op: "custom", access: 'read', method: "get",
+        name: 'Check enduser authentication',
+        path: '/enduser-is-authenticated',
+        description: "Checks the validity of an enduser's authToken",
+        parameters: { 
+          id: { validator: mongoIdStringValidator, required: true },
+          authToken: { validator: stringValidator5000, required: true },
+        },
+        returns: { 
+          isAuthenticated: { validator: booleanValidator, required: true }, 
+          enduser: { validator: 'enduser' }, 
+        } as any // todo: add enduser eventually, when validator defined
+      },
+      refresh_session: {
+        op: "custom", access: 'update', method: "post",
+        name: 'Refresh enduser authentication',
+        path: '/refresh-enduser-session',
+        description: "When called by an authenticated enduser, generates a new session",
+        parameters: { },
+        enduserOnly: true,
+        returns: { 
+          authToken: { validator: stringValidator, required: true }, 
+          enduser: { validator: 'enduser' }, 
+        } as any // todo: add enduser eventually, when validator defined
+      },
+      logout: {
+        op: "custom", access: 'update', method: "post",
+        name: 'Logout enduser',
+        path: '/logout-enduser',
+        description: "Logs out an enduser",
+        parameters: {},
+        returns: {},
+      },
+    },
+    publicActions: {
+      login: {
+        op: "custom", access: 'read', method: "post",
+        name: 'Login enduser',
+        path: '/login-enduser',
+        description: "Generates an authentication token for access to enduser-facing endpoints",
+        enduserOnly: true, // implemented as authenticate in enduser sdk only
+        parameters: { 
+          id: { validator: mongoIdStringValidator },
+          password: { validator: stringValidator100, required: true }, // required until optional challenge token available
+          phone: { validator: phoneValidator },
+          email: { validator: emailValidator },
+        },
+        returns: { authToken: { validator: stringValidator5000 } },
+      },
     },
-    defaultActions: DEFAULT_OPERATIONS,
   },
   api_keys: {
     info: {},
@@ -608,7 +654,7 @@ export const schema: SchemaV1 = {
         validator: mongoIdStringValidator,
         examples: [PLACEHOLDER_ID],
         readonly: true, 
-        initializer: (a, s) => (s as UserSession).userId,
+        initializer: (a, s) => (s as UserSession).id,
       },
       subject: {
         validator: stringValidator,
@@ -728,7 +774,7 @@ export const schema: SchemaV1 = {
       businessUserId: {
         validator: mongoIdStringValidator,
         readonly: true, // default to only self-sending, for now
-        initializer: (a, s) => (s as UserSession).userId,
+        initializer: (a, s) => (s as UserSession).id,
         dependencies: [{
           dependsOn: ['users'],
           dependencyField: '_id',
@@ -845,7 +891,7 @@ export const schema: SchemaV1 = {
       senderId: { 
         validator: mongoIdStringValidator,
         readonly: true, // create a separate endpoint for storing enduser chats
-        initializer: (a, s) => (s as UserSession).userId ?? (s as EnduserSession).enduserId,
+        initializer: (a, s) => (s as UserSession).id ?? (s as EnduserSession).id,
         examples: [PLACEHOLDER_ID],
         dependencies: [{ // can be userId or enduserId
           dependsOn: ['users', 'endusers'],
@@ -939,6 +985,17 @@ export const schema: SchemaV1 = {
       roles: {
         validator: listOfStringsValidator,
       },
+      avatar: {
+        validator: stringValidator100,
+        dependencies: [
+          {
+            dependsOn: ['files'],
+            dependencyField: 'secureName',
+            relationship: 'foreignKey',
+            onDependencyDelete: 'unset',
+          },
+        ]
+      },
     }
   },
   templates: {
@@ -971,5 +1028,72 @@ export const schema: SchemaV1 = {
         initializer: () => 'enduser'
       },
     }
+  },
+  files: {
+    info: {},
+    constraints: { unique: [], relationship: [] },
+    defaultActions: { read: {}, readMany: {}, update: {} },
+    fields: {
+      ...BuiltInFields, 
+      name: {
+        validator: stringValidator250,
+        required: true,
+      },
+      size: {
+        validator: fileSizeValidator,
+        required: true,
+      },
+      type: {
+        validator: fileTypeValidator,
+        required: true
+      },
+      secureName: {
+        validator: stringValidator250,
+        readonly: true,
+      },
+    },
+    enduserActions: { prepare_file_upload: {} },
+    customActions: {
+      prepare_file_upload: {
+        op: "custom", access: 'create', method: "post",
+        name: 'Prepare File Upload',
+        path: '/prepare-file-upload',
+        description: "Generates an upload link for a file, storing metadata as a File record.",
+        parameters: { 
+          name: {
+            validator: stringValidator250,
+            required: true,
+          },
+          size: {
+            validator: fileSizeValidator,
+            required: true,
+          },
+          type: {
+           validator: fileTypeValidator,
+            required: true
+          },
+        },
+        returns: { 
+          presignedUpload: {
+            validator: objectAnyFieldsValidator,
+          },
+          file: {
+            validator: 'file' as any, // todo: add file validator
+          },
+        },
+      },
+      file_download_URL: {
+        op: "custom", access: 'read', method: "get",
+        name: 'Generate File Download',
+        path: '/file-download-link',
+        description: "Generates a temporary download link for a file.",
+        parameters: { 
+          secureName: { validator: stringValidator250 },
+        },
+        returns: { 
+          downloadURL: { validator: stringValidator250 },
+        },
+      },
+    },
   }
 }

package/tsconfig.json

@@ -9,6 +9,6 @@
   "references": [
     { "path": "../constants" },
     { "path": "../validation" },
-    { "path": "../types" }
+    { "path": "../types-server" }
   ]
 }