Automate doc

.github/workflows/update-doc.yml

@@ -0,0 +1,37 @@
+name: Update docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  create-files:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install deps
+        run: npm install
+      - name: Build project
+        run: npm run build
+      - name: Create md files
+        run: npx typedoc --excludePrivate --out ./docs --plugin typedoc-plugin-markdown ./src
+      - name: Compile md files
+        run: npx concat-md --decrease-title-levels --ignore README.md --dir-name-as-title docs > docs/reference.md
+      - name: Update docs website
+        uses: car-on-sale/[email protected]
+        env:
+          API_TOKEN_GITHUB: ${{ secrets.WEBSITE_GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.WEBSITE_GITHUB_TOKEN }}
+        with:
+          source_folder: 'docs'
+          destination_repo: 'ScribeLabsAI/documentation'
+          destination_folder: 'docs/SDK/mi-node'
+          destination_base_branch: 'master'
+          destination_head_branch: 'mi-node-update'
+          commit_msg: 'docs(MINode): Update MI Node doc'
+          pr_title: 'Update MI Node doc'
+          pull_request_reviewers: 'EHadoux'
+          user_email: '[email protected]'
+          user_name: 'ailinvenerus'

.gitignore

@@ -86,6 +86,7 @@ typings/
 # Nuxt.js build / generate output
 .nuxt
 dist
+docs
 
 # Gatsby files
 .cache/

package.json

@@ -34,12 +34,15 @@
     "eslint-plugin-vitest": "^0.3.8",
     "prettier": "^3.0.0",
     "prettier-plugin-organize-imports": "^3.0.0",
+    "typedoc": "^0.25.4",
+    "typedoc-plugin-markdown": "^3.17.1",
     "typescript": "^5.0.2",
     "vitest": "^0.34.3"
   },
   "dependencies": {
     "@scribelabsai/auth": "^1.3.0",
     "aws-sigv4-fetch": "^2.1.1",
+    "concat-md": "^0.5.1",
     "zod": "^3.22.2"
   }
 }

src/index.ts

@@ -28,6 +28,10 @@ export class ScribeMIClient {
   credentials: Credentials | undefined;
   fetch: typeof fetch | undefined;
 
+  /**
+   * Construct an MI client.
+   * @param env - Environment vars
+   */
   constructor(env: Environment) {
     this.env = env;
     this.authClient = new Auth({
@@ -37,6 +41,14 @@ export class ScribeMIClient {
     });
   }
 
+  /**
+   * To authenticate a user.
+   * @param param - Username and password OR refreshToken.
+   * @param param.username - usually an email address.
+   * @param param.password - associated with this username.
+   *                   OR
+   * @param param.refreshToken - Refresh token to use.
+   */
   async authenticate(param: UsernamePassword | RefreshToken) {
     this.tokens = await this.authClient.getTokens(param);
     this.userId = await this.authClient.getFederatedId(this.tokens.idToken);
@@ -55,6 +67,9 @@ export class ScribeMIClient {
     });
   }
 
+  /**
+   * To reauthenticate a user without sending parameters. Must be called after authenticate.
+   */
   async reauthenticate() {
     if (!this.tokens || !this.userId) {
       throw new Error('Must authenticate before reauthenticating');
@@ -75,6 +90,14 @@ export class ScribeMIClient {
     });
   }
 
+  /**
+   * To call an endpoint.
+   * @param path - URL path to use, not including any prefix.
+   * @param outputSchema - The schema to validate the output against.
+   * @param args - Additional arguments to pass.
+   * @returns JSON response.
+   * @hidden
+   */
   async callEndpoint<T>(path: string, outputSchema: ZodType<T>, args?: RequestInit): Promise<T> {
     if (!this.fetch || !this.credentials) {
       throw new Error('Not authenticated');
@@ -95,6 +118,11 @@ export class ScribeMIClient {
     }
   }
 
+  /**
+   * To list the tasks.
+   * @param companyName - List tasks for a specific company.
+   * @returns List of tasks.
+   */
   async listTasks(companyName?: string): Promise<MITask[]> {
     const params = new URLSearchParams();
     params.append('includePresigned', 'true');
@@ -108,10 +136,20 @@ export class ScribeMIClient {
     return tasks;
   }
 
+  /**
+   * To get a task by jobid.
+   * @param jobid - Jobid of the task to get.
+   * @returns A task.
+   */
   async getTask(jobid: string): Promise<MITask> {
     return await this.callEndpoint(`/tasks/${jobid}`, GetMIOutputSchema);
   }
 
+  /**
+   * Fetch the model for a task.
+   * @param task - Task to fetch the model for.
+   * @returns Model.
+   */
   async fetchModel(task: MITask): Promise<MIModel> {
     if (!task.modelUrl) {
       throw new Error(`Cannot load model for task ${task.jobid}: model is not ready to export`);
@@ -125,6 +163,11 @@ export class ScribeMIClient {
     }
   }
 
+  /**
+   * To consolidate tasks.
+   * @param tasks - List of tasks to consolidate.
+   * @returns Consolidated model.
+   */
   async consolidateTasks(tasks: MITask[]): Promise<MICollatedModelFundPerformance> {
     const params = new URLSearchParams({
       jobids: tasks.map((task) => task.jobid).join(';'),
@@ -136,6 +179,15 @@ export class ScribeMIClient {
     return model;
   }
 
+  /**
+   * To submit a task.
+   * @param file - File to upload.
+   * @param props - The properties of the file.
+   * @param props.filetype - Type of file to submit.
+   * @param props.filename - Name of the file to submit.
+   * @param props.companyname - Name of the company to submit the file for.
+   * @returns Jobid of the task.
+   */
   async submitTask(
     file: Buffer,
     props: { filetype: MIFileType; filename?: string; companyname?: string }
@@ -157,6 +209,11 @@ export class ScribeMIClient {
     return jobid;
   }
 
+  /**
+   * To delete a task.
+   * @param task - Task to delete.
+   * @returns MITask deleted.
+   */
   async deleteTask(task: MITask) {
     return await this.callEndpoint(`/tasks/${task.jobid}`, DeleteMIOutputSchema, {
       method: 'DELETE',