V5

.azure/npm-publish.yml

@@ -0,0 +1,47 @@
+# This pipeline publishes the `@kth/canvas-api` package to npm
+pr: none
+trigger:
+  branches:
+    include:
+      - main
+      - v5
+
+variables:
+  - group: team-elarande-general-params
+
+steps:
+  - checkout: self
+    path: github
+
+  - task: NodeTool@0
+    inputs:
+      versionSource: "spec"
+      versionSpec: 20.x
+
+  - task: Npm@1
+    displayName: Run `npm ci`
+    inputs:
+      workingDir: "$(Pipeline.Workspace)/github"
+      command: ci
+
+  - task: Npm@1
+    displayName: Run `npm run build`
+    inputs:
+      workingDir: "$(Pipeline.Workspace)/github"
+      command: custom
+      customCommand: run build
+
+  - task: Npm@1
+    displayName: Run `npm test`
+    inputs:
+      workingDir: "$(Pipeline.Workspace)/github"
+      command: custom
+      customCommand: test
+
+  - task: Npm@1
+    displayName: Publish to npm
+    inputs:
+      workingDir: "$(Pipeline.Workspace)/github"
+      command: publish
+      publishRegistry: useExternalRegistry
+      publishEndpoint: $(npmServiceConnection)

README.md

@@ -4,172 +4,132 @@
 npm i @kth/canvas-api
 ```
 
-Node.JS HTTP client (for both TypeScript and JavaScript) based on [got](https://github.com/sindresorhus/got) for the [Canvas LMS API](https://canvas.instructure.com/doc/api/)
+Node.JS HTTP client (for both TypeScript and JavaScript) for the [Canvas LMS API](https://canvas.instructure.com/doc/api/)
 
 ## Getting Started
 
 First, generate a token by going to `«YOUR CANVAS INSTANCE»/profile/settings`. For example https://canvas.kth.se/profile/settings. Then you can do something like:
 
-```js
-const canvasApiUrl = process.env.CANVAS_API_URL;
-const canvasApiToken = process.env.CANVAS_API_TOKEN;
-const Canvas = require("@kth/canvas-api").default;
-
-async function start() {
-  console.log("Making a GET request to /accounts/1");
-  const canvas = new Canvas(canvasApiUrl, canvasApiToken);
-
-  const { body } = await canvas.get("accounts/1");
-  console.log(body);
-}
-
-start();
-```
-
-In TypeScript, use `import`:
-
 ```ts
-import Canvas from "@kth/canvas-api";
+import { CanvasApi } from "@kth/canvas-api";
 
 console.log("Making a GET request to /accounts/1");
-const canvas = new Canvas(canvasApiUrl, canvasApiToken);
+const canvas = new CanvasApi(
+  "<YOUR CANVAS INSTANCE>/api/v1",
+  "<YOUR CANVAS TOKEN>"
+);
 
-const { body } = await canvas.get("accounts/1");
-console.log(body);
+const { json } = await canvas.get("accounts/1");
+console.log(json);
 ```
 
-## Concepts
-
-### 🆕 New from v4. SIS Imports
-
-This package implements one function to perform SIS Imports (i.e. call the [POST sis_imports] endpoint).
-
-> Note: this is the only function that calls a **specific** endpoint. For other endpoints you should use `canvas.get`, `canvas.requestUrl`, `canvas.listItems` and `canvas.listPages`
+## Features
 
-[post sis_imports]: https://canvas.instructure.com/doc/api/sis_imports.html#method.sis_imports_api.create
+### SIS Imports
 
-### `listItems` and `listPages`
+Use the method `.sisImport()`
 
-This package does have pagination support which is offered in two methods: `listItems` and `listPages`. Let's see an example by using the `[GET /accounts/1/courses]` endpoint.
-
-If you want to get all **pages** you can use `listPages`:
+```ts
+import { CanvasApi } from "@kth/canvas-api";
 
-```js
-const canvas = new Canvas(canvasApiUrl, canvasApiToken);
+const canvas = new CanvasApi(
+  "<YOUR CANVAS INSTANCE>/api/v1",
+  "<YOUR CANVAS TOKEN>"
+);
 
-const pages = canvas.listPages("accounts/1/courses");
+const buffer = await readFile("<FILE PATH>");
 
-// Now `pages` is an iterator that goes through every page
-for await (const coursesResponse of pages) {
-  // `courses` is the Response object that contains a list of courses
-  const courses = coursesResponse.body;
+// Note: you must give the file name with the correct extension
+const file = new File([buffer], "test.csv");
 
-  for (const course of courses) {
-    console.log(course.id, course.name);
-  }
-}
+const { json } = await canvas.sisImport(file);
+console.log(json);
 ```
 
-To avoid writing two `for` loops like above, you can call `listItems`, that iterates elements instead of pages. The following code does exactly the same as before. Note that in this case, you will not have the `Response` object:
-
-```js
-const canvas = new Canvas(canvasApiUrl, canvasApiToken);
+If you need to pass extra parameters to Canvas, create a `FormData` object and pass it as `body` to the `request()` method:
 
-const courses = canvas.listItems("accounts/1/courses");
-
-// Now `courses` is an iterator that goes through every course
-for await (const course of courses) {
-  console.log(course.id, course.name);
-}
+```ts
+import { CanvasApi } from "@kth/canvas-api";
+
+const canvas = new CanvasApi(
+  "<YOUR CANVAS INSTANCE>/api/v1",
+  "<YOUR CANVAS TOKEN>"
+);
+
+const buffer = await readFile("<FILE PATH>");
+const file = new File([buffer], "test.csv");
+const formData = new FormData();
+formData.set("attachment", file);
+formData.set("key", "value");
+
+const { json } = await canvas.request(
+  "accounts/1/sis_import",
+  "POST",
+  formData
+);
+console.log(json);
 ```
 
-[get /accounts/1/courses]: https://canvas.instructure.com/doc/api/accounts.html#method.accounts.courses_api
+### Pagination
 
-### Typescript support
-
-This package does not contain type definitions to the objects returned by Canvas. If you want such types, you must define them yourself and pass it as type parameter to the methods in this library.
-
-For example, to get typed "account" objects:
+Use the method `.listPages` to automatically traverse pages.
 
 ```ts
-// First you define the "Account" type (or interface)
-// following the Canvas API docs: https://canvas.instructure.com/doc/api/accounts.html
-interface CanvasAccount {
-  id: number;
-  name: string;
-  workflow_state: string;
-}
-
-// Then, you can call our methods by passing your custom type as type parameter
-const { body } = await canvas.get<CanvasAccount>("accounts/1");
-
-console.log(body);
-```
-
-### Error handling
+import { CanvasApi } from "@kth/canvas-api";
 
-By default, this library throws `CanvasApiError` exceptions when it gets a non-200 HTTP response from the Canvas API. You can catch those exceptions with any of the methods:
+const canvas = new CanvasApi(
+  "<YOUR CANVAS INSTANCE>/api/v1",
+  "<YOUR CANVAS TOKEN>"
+);
 
-```ts
-const canvas = new Canvas(canvasApiUrl, "-------");
 const pages = canvas.listPages("accounts/1/courses");
 
-try {
-  for await (const coursesResponse of pages) {
-    const courses = coursesResponse.body;
-
-    for (const course of courses) {
-      console.log(course.id, course.name);
-    }
-  }
-} catch (err) {
-  if (err instanceof CanvasApiError) {
-    console.log(err.options.url);
-    console.log(err.response.statusCode);
-    console.log(err.message);
-  }
+for await (const { json } of pages) {
+  console.log(json);
 }
 ```
 
-#### Shorter error objects
+If the page returns a list of items, you can use `.listItems` to traverse through the items.
 
-By default, `CanvasApiError` thrown by this library contains a property `response` with a very big object. If you would like to have a smaller `response` in the error object, you can modify the `errorHandler` property:
+Note: the returned iterator does not include response headers
 
 ```ts
-import CanvasApi, { minimalErrorHandler } from "@kth/canvas-api";
-const canvas = new CanvasApi("...");
-canvas.errorHandler = minimalErrorHandler;
-```
+import { CanvasApi } from "@kth/canvas-api";
 
-#### Custom error objects
+const canvas = new CanvasApi(
+  "<YOUR CANVAS INSTANCE>/api/v1",
+  "<YOUR CANVAS TOKEN>"
+);
 
-You can also pass a custom function in the `.errorHandler` property: that function will be called with whatever is thrown by `got`. Read more about [errors in Got here](https://github.com/sindresorhus/got/blob/main/documentation/8-errors.md)
+const courses = canvas.listItems("accounts/1/courses");
 
-Notes:
+for await (const course of courses) {
+  console.log(course);
+}
+```
 
-- Argument `err` in the custom handler will be the error thrown by `got`, so it will never be `CanvasApiError`
-- Make sure the function you pass never returns something.
+### Type safety
 
-You can use this function to create your own error objects:
+This library parses JSON responses from Canvas and convert them as JavaScript object. If you want to check types in runtime, use a library like Zod:
 
 ```ts
-import CanvasApi from "@kth/canvas-api";
-
-const canvas = new CanvasApi("...");
-
-canvas.errorHandler = function customHandler(err: unknown): never {
-  if (err instanceof HTTPError) {
-    throw new CustomError(`Oh! An error! ${err.message}`);
-  }
-
-  throw err;
-};
+import { CanvasApi } from "@kth/canvas-api";
+import { z } from "zod";
+
+const canvas = new CanvasApi(
+  "<YOUR CANVAS INSTANCE>/api/v1",
+  "<YOUR CANVAS TOKEN>"
+);
+const accountSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  workflow_state: z.string(),
+});
+
+const { json } = client.get("accounts/1");
+const parsed = accountSchema.parse(json);
 ```
 
-## Design philosophy
-
-1. **Do not implement every endpoint**. This package does **not** implement every endpoint in Canvas API This package also does not implement type definitions for objects returned by any endpoint nor definition for parameters. That would make it unmaintainable.
-
-2. **Offer "lower-level" API** instead of trying to implement every possible feature, expose the "internals" to make it easy to extend.
+### Error handling
 
-   Example: you can use `.client` to get the `Got` instance that is used internally. With such object, you have access to all options given by the library [got](https://github.com/sindresorhus/got)
+This library returns instances of `CanvasApiError`. Check the [file `src/canvasApiError.ts`](./src/canvasApiError.ts) to see all the error classes that this library throws

eslint.config.mjs

@@ -0,0 +1,12 @@
+// @ts-check
+
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: ["dist/"],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended
+);

examples/error-handling-1.js

@@ -2,12 +2,10 @@
 /* eslint-disable */
 require("dotenv").config();
 const canvasApiUrl = process.env.CANVAS_API_URL;
-const canvasApiToken = process.env.CANVAS_API_TOKEN;
-const Canvas = require("../dist/index").default;
-const { CanvasApiError } = require("../dist/index");
+const { CanvasApi, CanvasApiResponseError } = require("@kth/canvas-api");
 
 async function start() {
-  const canvas = new Canvas(canvasApiUrl, "-------");
+  const canvas = new CanvasApi(canvasApiUrl, "-------");
   const pages = canvas.listPages("accounts/1/courses");
 
   // Now `pages` is an iterator that goes through every page
@@ -21,10 +19,10 @@ async function start() {
       }
     }
   } catch (err) {
-    if (err instanceof CanvasApiError) {
-      console.log(err.options.url);
+    if (err instanceof CanvasApiResponseError) {
       console.log(err.response.statusCode);
       console.log(err.message);
+      console.log(err.response.text);
     }
   }
 }

examples/get-root-account.js

@@ -2,11 +2,11 @@
 require("dotenv").config();
 const canvasApiUrl = process.env.CANVAS_API_URL;
 const canvasApiToken = process.env.CANVAS_API_TOKEN;
-const Canvas = require("../dist/index").default;
+const { CanvasApi } = require("@kth/canvas-api");
 
 async function start() {
   console.log("Making a GET request to /accounts/1");
-  const canvas = new Canvas(canvasApiUrl, canvasApiToken);
+  const canvas = new CanvasApi(canvasApiUrl, canvasApiToken);
 
   const { body } = await canvas.get("accounts/1");
   console.log(body);

examples/list-courses-1.js

@@ -3,10 +3,10 @@
 require("dotenv").config();
 const canvasApiUrl = process.env.CANVAS_API_URL;
 const canvasApiToken = process.env.CANVAS_API_TOKEN;
-const Canvas = require("../dist/index").default;
+const { CanvasApi } = require("@kth/canvas-api");
 
 async function start() {
-  const canvas = new Canvas(canvasApiUrl, canvasApiToken);
+  const canvas = new CanvasApi(canvasApiUrl, canvasApiToken);
 
   const pages = canvas.listPages("accounts/1/courses");