eng-1983 initial stab at crossAppContracts

Author: maparent

packages/database/src/crossAppContracts.ts

@@ -15,12 +15,15 @@ type DbRef = {
 export type Ref = LocalRef | DbRef;
 
 // Common attributes for most types
-type CrossAppBase = LocalRef & {
+type BaseAttributes = {
   createdAt: Date;
   modifiedAt?: Date;
   author: Ref;
 };
 
+// Common attributes for most types
+type CrossAppBase = LocalRef & BaseAttributes;
+
 type SpaceRef = DbRef | { url: string; sourceApp: Enums<"Platform"> };
 
 export type LocalOrRemoteRef =
@@ -35,6 +38,19 @@ export type LocalOrRemoteRef =
       rid: string;
     };
 
+type WithOptionalLocalRef<Extra> = (LocalRef & Extra) | Extra;
+
+/*
+  Note on Inline vs Standalone:
+  The db `upsert_...` functions allow to put some objects inline inside related objects instead of passing a reference.
+  Those objects will either get upserted or resolved by the upsert functions.
+  When we provide an inline object, some shared attributes can be specified in the enclosing object.
+  Hence, the inline version of the object has less required attributes than the standalone version.
+*/
+
+// Partial version of above, utility type for functions that can receive many of the above.
+export type InlineAbstractBase = WithOptionalLocalRef<Partial<BaseAttributes>>;
+
 // A node schema
 export type CrossAppNodeSchema = CrossAppBase & {
   label: string;
@@ -64,27 +80,80 @@ export type CrossAppEmbedding = {
   embedding?: Enums<"EmbeddingName">;
 };
 
-// A Content object. It can be put inline inside a concept.
-// Missing CrossAppBase attributes are inferred from enclosing object.
-export type InlineCrossAppContent = Partial<CrossAppBase> & {
+// An asset reference
+export type CrossAppAsset = {
+  content: ArrayBuffer;
+  mimetype: string;
+  createdAt: Date;
+  modifiedAt?: Date;
+  filepath?: string;
+};
+
+// Document fields
+type CrossAppDocumentExtras = {
+  // MIME type
+  contentType: string;
+};
+
+// An inline document, to put inside Content or Concept.
+// Currently, we fully infer Documents (setting content_as_document=true)
+// since our nodes are pages; so this is not used yet.
+export type InlineCrossAppDocument = WithOptionalLocalRef<
+  Partial<BaseAttributes> & CrossAppDocumentExtras
+>;
+
+// A standalone document, for `upsert_documents`. Not currently used.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type StandaloneCrossAppDocument = LocalRef &
+  BaseAttributes &
+  CrossAppDocumentExtras;
+
+// Content fields
+type CrossAppContentExtras = {
   value: string;
   embedding?: CrossAppEmbedding;
   scale?: Enums<"Scale">;
+  partOf?: Ref;
+  assets?: CrossAppAsset[];
+  document?: InlineCrossAppDocument;
   contentType?: ContentType;
 };
 
+// An inline content object, to be put inside a Concept.
+export type InlineCrossAppContent = Partial<CrossAppBase> &
+  CrossAppContentExtras;
+
+// A standalone content object, for `upsert_content`
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type StandaloneCrossAppContent = LocalRef &
+  BaseAttributes &
+  CrossAppContentExtras;
+
 // An inline Content with obligatory typing
 export type InlineCrossAppTypedContent = InlineCrossAppContent & {
   contentType: ContentType;
 };
 
+// A platform account
+// either standalone for `upsert_account_in_space`,
+// or inline in Content or Concept
+export type CrossAppAccount = {
+  accountLocalId: string;
+  name?: string;
+  email?: string;
+  // agentType: Enums<"AgentType"> = 'person'  // inferred
+  // dgAccount?: string; // uuid
+};
+
 // A node instance
 export type CrossAppNode = CrossAppBase & {
   nodeType: Ref;
   content: {
     direct: InlineCrossAppContent;
     full: InlineCrossAppTypedContent;
   };
+  // This is a way to define document globally for all contents
+  document?: InlineCrossAppDocument;
 };
 
 // A relation instance