eng-1983 initial stab at crossAppContracts

Author: maparent

packages/database/src/crossAppContracts.ts

@@ -15,12 +15,42 @@ 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 =
+  | LocalRef
+  | {
+      localId: string;
+      // infer space from context if absent.
+      space?: SpaceRef;
+    }
+  | {
+      // A string that contains combined space and localId
+      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;
@@ -50,25 +80,85 @@ 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
+export type CrossAppRelation = CrossAppBase & {
+  relationType: Ref;
+  source: LocalOrRemoteRef;
+  destination: LocalOrRemoteRef;
 };