V5

.azure/npm-publish.yml

@@ -0,0 +1,54 @@
+# This pipeline publishes the `@kth/canvas-api` package to npm
+pr: none
+trigger: none
+
+variables:
+  - group: elarande-general-params
+
+resources:
+  repositories:
+    - repository: stratus-templates
+      type: git
+      name: Cloud Excellence Team/stratus-templates
+      ref: main
+
+extends:
+  template: templates/security/security-scans.yml@stratus-templates
+  parameters:
+    break: false
+    steps:
+      - checkout: self
+        path: github
+
+      - task: NodeTool@0
+        inputs:
+          versionSource: "spec"
+          versionSpec: 20.x
+
+      - task: Npm@1
+        displayName: Run `npm ci` for `@kth/style`
+        inputs:
+          workingDir: "$(Pipeline.Workspace)/github/@kth/style"
+          command: ci
+
+      - task: Npm@1
+        displayName: Run `npm run build` for `@kth/style`
+        inputs:
+          workingDir: "$(Pipeline.Workspace)/github/@kth/style"
+          command: custom
+          customCommand: run build
+
+      - task: Npm@1
+        displayName: Run `npm test` for `@kth/style`
+        inputs:
+          workingDir: "$(Pipeline.Workspace)/github/@kth/style"
+          command: custom
+          customCommand: test
+
+      - task: Npm@1
+        displayName: Publish `@kth/style` to npm
+        inputs:
+          workingDir: "$(Pipeline.Workspace)/github/@kth/style"
+          command: publish
+          publishRegistry: useExternalRegistry
+          publishEndpoint: $(npmServiceConnection)

.prettierignore

@@ -4,6 +4,7 @@ build-information.js
 node_modules
 .env
 dist
+nix
 
 # VS Code specific
 .vscode

README.md

@@ -4,172 +4,163 @@
 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
+## Features
 
-### 🆕 New from v4. SIS Imports
+### SIS Imports
 
-This package implements one function to perform SIS Imports (i.e. call the [POST sis_imports] endpoint).
+Use the method `.sisImport()`
 
-> 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`
+```ts
+import { CanvasApi } from "@kth/canvas-api";
 
-[post sis_imports]: https://canvas.instructure.com/doc/api/sis_imports.html#method.sis_imports_api.create
+const canvas = new CanvasApi(
+  "<YOUR CANVAS INSTANCE>/api/v1",
+  "<YOUR CANVAS TOKEN>"
+);
 
-### `listItems` and `listPages`
+const buffer = await readFile("<FILE PATH>");
 
-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.
+// Note: you must give the file name with the correct extension
+const file = new File([buffer], "test.csv");
 
-If you want to get all **pages** you can use `listPages`:
+const { json } = await canvas.sisImport(file);
+console.log(json);
+```
 
-```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 pages = canvas.listPages("accounts/1/courses");
+```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);
+```
 
-// 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;
+### Pagination
 
-  for (const course of courses) {
-    console.log(course.id, course.name);
-  }
-}
-```
+Use the method `.listPages` to automatically traverse pages.
 
-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:
+```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 courses = canvas.listItems("accounts/1/courses");
+const pages = canvas.listPages("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);
+for await (const { json } of pages) {
+  console.log(json);
 }
 ```
 
-[get /accounts/1/courses]: https://canvas.instructure.com/doc/api/accounts.html#method.accounts.courses_api
+If the page returns a list of items, you can use `.listItems` to traverse through the items.
 
-### 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:
+Note: the returned iterator does not include response headers
 
 ```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;
-}
+import { CanvasApi } from "@kth/canvas-api";
 
-// Then, you can call our methods by passing your custom type as type parameter
-const { body } = await canvas.get<CanvasAccount>("accounts/1");
+const canvas = new CanvasApi(
+  "<YOUR CANVAS INSTANCE>/api/v1",
+  "<YOUR CANVAS TOKEN>"
+);
+
+const courses = canvas.listItems("accounts/1/courses");
 
-console.log(body);
+for await (const course of courses) {
+  console.log(course);
+}
 ```
 
-### Error handling
+### Rate Limiting
 
-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:
+CanvasApi will automatically handle rate limiting by throttling calls. Throttling is applied globally for all your CanvasApi instances. This is done using a FIFO-queue where each call is resolved sequentially. If you have slow calls that you want to resolve in parallell you can disable throttling:
 
 ```ts
-const canvas = new Canvas(canvasApiUrl, "-------");
-const pages = canvas.listPages("accounts/1/courses");
+const canvas = new CanvasApi("https://canvas.local/", "");
 
-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);
-  }
-}
+const canvasWithoutThrottling = new CanvasApi("https://canvas.local/", "", {
+  disableThrottling: true,
+});
 ```
 
-#### Shorter error objects
+You can mix instances with and without throttling.
+
+### Type safety
 
-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:
+This library parses JSON responses from Canvas and converts them to JavaScript object. If you want to check types at runtime, use a validation library:
 
 ```ts
-import CanvasApi, { minimalErrorHandler } from "@kth/canvas-api";
-const canvas = new CanvasApi("...");
-canvas.errorHandler = minimalErrorHandler;
+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);
 ```
 
-#### Custom error objects
-
-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)
-
-Notes:
-
-- 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.
+### Error handling
 
-You can use this function to create your own error objects:
+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
 
-```ts
-import CanvasApi from "@kth/canvas-api";
+## Development
 
-const canvas = new CanvasApi("...");
+### Dev-Env as code with `nix-shell`
 
-canvas.errorHandler = function customHandler(err: unknown): never {
-  if (err instanceof HTTPError) {
-    throw new CustomError(`Oh! An error! ${err.message}`);
-  }
+We use nix package manager to get a consistent developer experience across devices (Linux/macOS):
 
-  throw err;
-};
-```
+- shell.nix -- equivalent of package.json but for system packages
+- .nix/source.json -- equivalent of package-lock.json but pinned to a commit in the nix package repo
 
-## Design philosophy
+[Installing the Required Nix Tools](https://confluence.sys.kth.se/confluence/pages/viewpage.action?pageId=193409170) and setting up your editor. This page also contains instructions or pointers for how to set up your editor.
 
-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.
+Run `nix-shell` in the root directory and it will install the required packages for the project. You won't need nvm or similar to switch Node.js version and you will get the correct version of Node.js, az, openssl, etc.
 
-2. **Offer "lower-level" API** instead of trying to implement every possible feature, expose the "internals" to make it easy to extend.
+#### Setting up your own environment
 
-   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)
+The Nixpkgs-setup is a declarative configuration of the development environment. You can choose to install the packages manually on your local system.

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
+);