diff --git a/.github/workflows/update-doc.yml b/.github/workflows/update-doc.yml new file mode 100644 index 0000000..2e586f9 --- /dev/null +++ b/.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/action-pull-request-another-repo@v1.3.1 + 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: 'ailin@scribelabs.ai' + user_name: 'ailinvenerus' diff --git a/.gitignore b/.gitignore index 1f3d5d1..c9b7051 100644 --- a/.gitignore +++ b/.gitignore @@ -86,6 +86,7 @@ typings/ # Nuxt.js build / generate output .nuxt dist +docs # Gatsby files .cache/ diff --git a/package.json b/package.json index c497249..2cdd046 100644 --- a/package.json +++ b/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" } } diff --git a/src/index.ts b/src/index.ts index 83a3290..cda7a8f 100644 --- a/src/index.ts +++ b/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(path: string, outputSchema: ZodType, args?: RequestInit): Promise { 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 { 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 { 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 { 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 { 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',