Better error handling

This release comes with some enhancements regarding error handling

Shorter error objects

By default, CanvasApiError thrown by this library contains a property response with a very big object. If users would like to have a smaller response in the error object, they can modify the errorHandler property:

import CanvasApi, { minimalErrorHandler } from "@kth/canvas-api";
const canvas = new CanvasApi("...");
canvas.errorHandler = minimalErrorHandler;

(this shorter error objects might be the default one in the upcoming breaking version)

Custom error objects

Users 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

For example:

import CanvasApi from "@kth/canvas-api";
const canvas = new CanvasApi("...");
canvas.errorHandler = function customHandler(err: unknown) {
  if (err instanceof Error) {
    console.error(err.message);
  }
  throw err;
};

v4.1.0

Minor changes

Now CanvasAPI constructor will throw a TypeError when called using an invalid apiUrl. In such cases, this library already throws an error but later (when doing the first call to Canvas).

So this changes makes it easier for consumers to see where the error come from

v4. The Typescript release

From now on, this package is written in Typescript instead of JavaScript!

🎉 Special thanks to

• @jhsware at KTH for helping with the TypeScript migration and the migration plan (deprecating 3.x and so on)
• @ssciolla for giving us feedback and reporting that module.exports doesn't work as we have expected #29

Breaking changes

New way to import

Due to inconsistencies between how ES Modules, TypeScript modules and CommonJS works, we decided to take a decision and choose one as the primary way to import this package. We have decided to support in this order: TypeScript first, CommonJS second and ES6 last.

This means that this package must be imported as follow:

TypeScript

import CanvasAPI from "@kth/canvas-api";

CommonJS

const CanvasAPI = require("@kth/canvas-api").default;

Non breaking changes

New method names

To add more clarity about what are the methods, we have decided to rename them as follow:

• canvas.list becomes canvas.listItems
• canvas.listPaginated becomes canvas.listPages
• canvas.requestUrl becomes canvas.request

Old methods (.list and .listPaginated) are deprecated and will emit warnings if you use them.

New signature for listPages

Since listPages returns an iterator over pages and each of them is a different request to the Canvas API, the returned object iterates over Response objects instead of the body.

sendSis is deprecated in favor of sisImport

Previously, the sendSis method accepted three parameters: endpoint, attachment and body. However, at KTH we always call this function with the same parameters (endpoint = accounts/1/sis_import and body = {}) so we decided to drop the parameters and just accept attachment.

New CanvasApiError object

Whenever the request doesn't return a 200, the package will throw a custom CanvasApiError object. This class is also exported so you can use it to catch our methods:

import CanvasApi, { CanvasApiError } from "@kth/canvas-api";

const canvas = new CanvasApi(...);

try {
  await canvas.get(...)
} catch (err) {
  if (err instanceof CanvasApiError) {
    // handle
  }
}

New .client property

Now, once you construct the CanvasAPI instance, you will have .client property that contains the Got client used under the hood. That way you get all the features of the library Got (and we don't need to implement things that Got already has)

v3.0.2

This version fixes a bug in the .sendSis method caused by the library form-data. The library could throw errors even when using async functions (like sendSis) leading to uncaught exceptions even if the function call is wrapped in a try-catch block

v3.0.1

This version fixes a bug in .requestUrl method. Before the fix, body was not properly parsed as JSON and therefore not sent.

Got 11. Classes

This PR is a major release:

• It uses got 11 internally instead of got 9

Breaking changes

• CanvasAPI is now a class and therefore must be constructed using new
• Drop support to endpoints with a leading slash. get("/courses") is no longer valid and must be replaced with get("courses").
• Drop support for debug
• Drop support for the log option in the constructor.

Send CSV files

New function: CanvasClient.sendSis(endpoint, filePath, parameters)

Now, it is possible to send CSV files through the API by indicating the Canvas endpoint to send the file and the path of such file. Extra parameters can be sent as well. The request is going to be a POST with a content-type: multipart/form-data header.

Minor changes

New way of debugging. Deprecation of log parameter

• New recommended way for getting detailed logs: set an environmental variable DEBUG=* or DEBUG=canvas-api. Passing log (function) as parameter in Canvas constructor is now deprecated.

Deprecations and more descriptive messages:

• CanvasClient.requestUrl(endpoint, method) is deprecated for GET requests. Users should use .get(), .list() and .listPaginated(). For retro-compatibility reasons, the default value of parameter method is kept to GET even being this value the deprecated one.
• CanvasClient.list(endpoint) throws more descriptive error if the endpoint doesn't return an array of items. Users should use get() for getting single resources instead of lists of them.

TypeScript and ECMAScript modules ready (experimental)

• The package includes an ECMAScript module version of it under the path /esm ready to be imported. The same path includes types for its usage from TypeScript:

  import Canvas from '@kth/canvas-api/esm'

  Note that this feature is experimental and the path /esm can change in the future

Switch from request-promise to got

Switched the underlying HTTP request library from request-promise to got.
Due to some incompatibilities the major version was increased.

Augmented Iterators

New feature. Augmented Iterators

Now, it's easier to convert from iterators to arrays. Functions that returned async iterators, list() and listPaginated() return now an extended version of those including an toArray() method

v1.0.3

Fix a bug in list() and listPaginated(): those functions didn't send all query parameters on successive calls to API