Merge pull request #207 from desci-labs/m0ar/nodes-lib

Create `nodes-lib`

.env.example

@@ -90,8 +90,9 @@ ORCID_API_DOMAIN=https://api.sandbox.orcid.org
 ORCID_CLIENT_ID=
 ORCID_CLIENT_SECRET=
 
-REPO_SERVER_URL=http://host.docker.internal:5445
+REPO_SERVER_URL=http://host.docker.internal:5484
 REPO_SERVICE_SECRET_KEY=secretrepo
+
 # Ceramic publish feature toggle, set to 1 for active
 TOGGLE_CERAMIC=
 # If above is set, clone `@desci-labs/desci-codex` and put the path to it here

.github/workflows/build-and-test.yaml

@@ -58,7 +58,6 @@ jobs:
       - name: Run tests
         run: |
           cd desci-server && export DOCKER_BUILDKIT=1 && yarn && yarn test
-          echo "exit code $?"
           if [ $? -ne 0 ]; then
             exit 1
-          fi
+          fi

Makefile

@@ -3,6 +3,7 @@ build: .env desci-contracts/.env
 	$(MAKE) -C desci-models build
 	$(MAKE) -C desci-contracts build
 	$(MAKE) -C desci-server install
+	$(MAKE) -C desci-repo install
 
 .PHONY: sterile
 sterile: clean-rec
@@ -23,6 +24,7 @@ clean-rec:
 	$(MAKE) -C desci-contracts clean
 	$(MAKE) -C desci-models clean
 	$(MAKE) -C desci-server clean
+	$(MAKE) -C desci-repo clean
 
 .PHONY: .env
 .env: nodes-media/.env desci-repo/.env

README.md

@@ -75,6 +75,11 @@ This is a Typescript types library that describes a spec for Research Objects. I
 This is a NodeJS backend that manages draft Nodes. It maintains a user auth, verifies wallet credentials, offers 2FA to users, and is the main system that orchestrates between microservices. It maintains version history for each update to Nodes. It interfaces with a Graph index to implement the [DPID](https://dpid.org) Resolution Scheme.
 <br><br>
 
+## **nodes-lib**
+
+A library for programmatically interacting with Nodes, basically allowing automation of actions possible in the webapp. See separate documentation in the [README](./nodes-lib/README.md)
+<br><br>
+
 ## **desci-art-viewer**
 
 Nobody knows why this is still here, but it implements a React+Three.js 3d torus that plays [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life) on the surface of the torus. We were totally inspired by [this gif on Wikipedia](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life#/media/File:Trefoil_knot_conways_game_of_life.gif) and it only seems to work on Mac/Linux right now, YMMV.

bootstrapCeramic.sh

@@ -15,7 +15,7 @@ CTX="[bootstrapCeramic.sh]"
 set -euo pipefail
 trap catch ERR
 catch() {
-  echo "$CTX script failed"
+  echo "$CTX script failed (are CODEX_REPO_PATH and TOGGLE_CERAMIC set in .env?)"
   exit 1
 }
 
@@ -43,6 +43,13 @@ fi
 
 # Setup desci-codex and deploy composites
 pushd "$CODEX_REPO_PATH"
+
+# Check that the node admin secret is set up, otherwise the model ID's wont be correct
+if [ ! -f "packages/composedb/admin_seed.txt" ]; then
+  echo "$CTX Composites need to be deployed with the ceramic node admin seed for the local node, as the model IDs aren't deterministic otherwise"
+  exit 1
+fi
+
 if [[ ! -d "node_modules" ]]; then
   echo "$CTX installing deps desci-codex..."
   npm ci

desci-models/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desci-labs/desci-models",
-  "version": "0.2.1",
+  "version": "0.2.3-rc1",
   "description": "Data models for DeSci Nodes",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,7 +16,7 @@
     "test": "mocha -r ts-node/register --inspect tests/**/*.test.ts",
     "coverage": "nyc -r lcov -e .ts -x \"*.test.ts\" npm run test",
     "build": "tsc",
-    "publish": "npm publish --access public",
+    "doPublish": "npm publish --access public",
     "generate": "ts-interface-builder src/ResearchObject.ts src/RoCrate.ts --ignore-generics"
   },
   "author": "",

desci-models/src/ResearchObject.ts

@@ -16,19 +16,34 @@ export interface IpldUrl {
 }
 
 export interface ResearchObjectV1 extends ResearchObject {
+  /** Version of the research object schema*/
   version: 'desci-nodes-0.1.0' | 'desci-nodes-0.2.0' | 1;
+  /** Human-readable title of the publication */
   title?: string;
+  /** Human-readable desciption */
   description?: string;
+  /** The license that applies unless overriden with a component */
   defaultLicense?: string;
+  /** CID of a cover image to the publication */
   coverImage?: string | IpldUrl;
+  /** Metadata additions to DAG entires, or stand-alone entries like external links */
   components: ResearchObjectV1Component[];
+  /** @deprecated */
   validations?: ResearchObjectV1Validation[];
+  /* @deprecated **/
   attributes?: ResearchObjectV1Attributes[];
+  /** History for the object. Not part of the manifest, but can be populated
+  * by an pplication */
   history?: ResearchObjectV1History[];
+  /** @deprecated */
   tags?: ResearchObjectV1Tags[];
+  /** Organizations affiliated with the publication */
   organizations?: ResearchObjectV1Organization[];
+  /** Assigned dPID of the object, allowing finding the PID from the manifest */
   dpid?: ResearchObjectV1Dpid;
+  /** Research fields relevant for the publication */
   researchFields?: string[];
+  /** Contributors to this publication */
   authors?: ResearchObjectV1Author[];
 }
 
@@ -46,35 +61,68 @@ export interface ResearchObjectV1Tags {
   name: string;
 }
 
+/**
+ * Path-invariant metadata about a part of the research object.
+ * Can be used to tag a directory as code or data, mark a pdf file as
+ * as the main manuscript, add an external URL to the drive, et cetera.
+ *
+ * Mainly used through extension. See PdfComponent and DataComponent for
+ * example.
+*/
 export interface ResearchObjectV1Component {
+  /** Random UUID to identify the component, because paths and CIDs are
+   * neither unique nor stable.
+  */
   id: string;
+  /** Human-readable description of the component. */
   name: string;
+  /** Type of payload, which indicates to an app what to do with it. */
   type: ResearchObjectComponentType | ResearchObjectComponentTypeMap;
+  /** @deprecated visual representation for the component */
   icon?: any;
+  /** Description of the component content, see interface extenders. */
   payload: any;
+  /** @deprecated Preferred component to initially load in an app. */
   primary?: boolean;
+  /** Mark component as particularly interesting. */
   starred?: boolean;
 }
 
+/**
+ * Contributor listing for a research object.
+*/
 export interface ResearchObjectV1Author {
+  /** Name of the contributor */
   name: string;
+  /** Orcid handle of the contributor */
   orcid?: string;
+  /** Google Scholar profile of the contributor */
   googleScholar?: string;
+  /** Type of role in the publication */
   role: ResearchObjectV1AuthorRole;
+  /** Organizations the contributor is affiliated with */
   organizations?: ResearchObjectV1Organization[];
+  /** GitHub profile of the contributor */
   github?: string;
 }
 
 export interface ResearchObjectV1History {
   title: string;
-  author?: any; // does not refer to ResearchObject author for credit purpose, refers to the on-chain identity of the account who made the publication, this should not be stored in manifest and used in client only
+  /** does not refer to ResearchObject author for credit purpose, refers to
+   * the on-chain identity of the account who made the publication, this
+   * should not be stored in manifest and used in client only
+  */
+  author?: any;
   content: string;
   date?: number; // utc seconds
   transaction?: ResearchObjectTransaction;
 }
 
+/** Record of publication in the dPID registry contracts */
 export interface ResearchObjectTransaction {
+  /** Transaction hash in hex format */
   id: string;
+  /** Hex-encoded manifest CID as stored in the contract */
   cid: string;
   chainId?: string;
 }
@@ -125,7 +173,8 @@ export enum ResearchObjectComponentType {
   PDF = 'pdf',
   CODE = 'code',
   VIDEO = 'video',
-  TERMINAL = 'terminal', // not used, TODO: remove
+  /** @deprecated remove at will */
+  TERMINAL = 'terminal',
   DATA = 'data',
   LINK = 'link', // external link
 }
@@ -172,15 +221,24 @@ export type ResearchObjectComponentSubtypes =
   | ResearchObjectComponentLinkSubtype;
 
 export interface CommonComponentPayload {
+  /** Generic title of component */
   title?: string;
+  /** @deprecated Keyword metadata for component */
   keywords?: string[];
+  /** Description of component */
   description?: string;
+  /** License of component, if other than research object default */
   licenseType?: string;
-  path?: string;
+  /** Path of component in the drive, starting with `root` */
+  path: string;
 }
 
 export interface PdfComponentPayload {
-  url: string;
+  /** @deprecated CID of document, as stored in the drive */
+  url?: string;
+  /** CID of document, as stored in the drive */
+  cid: string;
+  /** Annotations on the document */
   annotations?: PdfAnnotation[];
 }
 
@@ -206,6 +264,19 @@ export interface DataComponentPayload {
   subMetadata: Record<Path, DataComponentMetadata>;
 }
 
+export interface CodeComponentPayload {
+  /** The main programming language of the code in the component */
+  language?: string;
+  /** @deprecated */
+  code?: string;
+  /** @deprecated CID of the component target */
+  url?: string;
+  /** CID of the component target */
+  cid: string;
+  /** Source URL, if externally imported code bundle */
+  externalUrl?: string;
+}
+
 export interface DataBucketComponent extends ResearchObjectV1Component {
   type: ResearchObjectComponentType.DATA_BUCKET;
   id: 'root';
@@ -237,13 +308,12 @@ export interface DataComponent extends ResearchObjectV1Component {
 export interface CodeComponent extends ResearchObjectV1Component {
   type: ResearchObjectComponentType.CODE;
   subtype?: ResearchObjectComponentCodeSubtype;
-  payload: {
-    language?: string;
-    code?: string;
-    url?: string;
-    externalUrl?: string;
-  } & CommonComponentPayload;
+  payload: CodeComponentPayload & CommonComponentPayload;
 }
+
+/** 
+ * @deprecated remove at will
+*/
 export interface TerminalComponent extends ResearchObjectV1Component {
   type: ResearchObjectComponentType.TERMINAL;
   payload: {
@@ -307,3 +377,43 @@ export enum ResearchObjectV1AuthorRole {
  */
 export type ResearchObjectComponentTypeMap = Record<FileExtension, ResearchObjectComponentType>;
 export type FileExtension = string;
+
+/** A semi-complete selection of license choices */
+export type License = 
+  | 'CC-BY-4.0'
+  | 'CC-BY'
+  | 'CC-BY-SA-4.0'
+  | 'CC-BY-SA'
+  | 'CC-BY-ND-4.0'
+  | 'CC-BY-ND'
+  | 'CC-BY-NC-4.0'
+  | 'CC-BY-NC'
+  | 'CC-BY-NC-SA-4.0'
+  | 'CC-BY-NC-SA'
+  | 'CC-BY-NC-ND-4.0'
+  | 'CC-BY-NC-ND'
+  | 'CC0-1.0'
+  | 'CC BY'
+  | 'CC BY-SA'
+  | 'CC BY-ND'
+  | 'CC BY-NC'
+  | 'CC BY-NC-SA'
+  | 'CC BY-NC-ND'
+  | 'CC0'
+  | 'GPL-3.0'
+  | 'MIT License'
+  | 'Apache License 2.0'
+  | 'Apache 2.0'
+  | 'Mozilla Public License 2.0'
+  | 'MPL 2.0'
+  | 'MIT'
+  | 'BSD-3-Clause'
+  | 'BSD-2-Clause'
+  | 'Apache-2.0'
+  | 'LGPL-3.0'
+  | 'LGPL-2.1'
+  | 'MPL-2.0'
+  | 'CDDL-1.0'
+  | 'EPL-2.0'
+  | 'AGPL-3.0'
+  | 'Unlicense';

desci-models/src/automerge.ts

@@ -0,0 +1,57 @@
+/**
+ * This file contains automerge actions for modifying the manifest file.
+ * This can be used by applications who wish to build a responsive,
+ * multi-client application for editing the manifest.
+ *
+ * @package
+*/
+
+import {
+  ResearchObjectComponentTypeMap,
+  ResearchObjectV1Author,
+  ResearchObjectV1Component,
+  ResearchObjectV1Dpid
+} from "./ResearchObject";
+
+export type ManifestActions =
+  | { type: 'Add Components'; components: ResearchObjectV1Component[] }
+  | { type: 'Delete Components'; paths: string[] }
+  | { type: 'Rename Component'; path: string; fileName: string }
+  | { type: 'Rename Component Path'; oldPath: string; newPath: string }
+  | {
+      type: 'Update Component';
+      component: ResearchObjectV1Component;
+      componentIndex: number;
+    }
+  | {
+      type: 'Assign Component Type';
+      component: ResearchObjectV1Component;
+      componentTypeMap: ResearchObjectComponentTypeMap;
+    }
+  | { type: 'Set Drive Clock'; time: string }
+  // frontend changes to support
+  | { type: 'Update Title'; title: string }
+  | { type: 'Update Description'; description: string }
+  | { type: 'Update License'; defaultLicense: string }
+  | { type: 'Update ResearchFields'; researchFields: string[] }
+  | { type: 'Add Component'; component: ResearchObjectV1Component }
+  | { type: 'Delete Component'; path: string }
+  | { type: 'Add Contributor'; author: ResearchObjectV1Author }
+  | { type: 'Remove Contributor'; contributorIndex: number }
+  | { type: 'Pin Component'; path: string }
+  | { type: 'UnPin Component'; path: string }
+  | {
+      type: 'Update Component';
+      component: ResearchObjectV1Component;
+      componentIndex: number;
+    }
+  | {
+      type: 'Publish Dpid';
+      dpid: ResearchObjectV1Dpid;
+    }
+  | { type: 'Remove Dpid' }
+  |
+    {
+      type: "Update CoverImage";
+      cid: string | undefined;
+    };