# caccl-grade-passback
Sends LTI 1.1 grade passback to Canvas. Support text and url submissions and overall score.

## Part of the CACCL library
**C**anvas  
**A**pp  
**C**omplete  
**C**onnection  
**L**ibrary

## Usage

To send pass grades back to Canvas, import this module and call it with three objects: `request`, `info`, and `credentials` (see below for descriptions of each).

```ts
import sendPassback from 'caccl-grade-passback';

await sendPassback({
    request,
    info,
    credentials,
});
```

## Arguments

### request

The request object contains all of the grade information to send to Canvas.

_Including a Grade:_

> Either add the total score by including `request.score`:
> 
> ```ts
> // Give the student 15 out of 20 points (that's 75%)
> const request = {
>   score: 15,
>   ...
> };
> ```
> 
> ...or add the percentage of the possible points by including `request.percent`:
> 
> ```ts
> // Give the student 15 out of 20 points (that's 75%)
> const request = {
>   percent: 75,
>   ...
> };
> ```

_Including a Submission:_

> Only two types of submissions are supported: text submissions and url submissions.
> 
> To add a text submission, include `request.text`:
> 
> ```ts
> const request = {
>   ...
>   text: 'Body of the student submission',
>   ...
> };
> ```
> 
> To add a url submission, include `request.url`:
> 
> ```ts
> const request = {
>   ...
>   url: 'https://url.of/student/submission',
>   ...
> };
> ```

_Including a "Submitted At" Timestamp:_

> To add a submission timestamp, include `request.submittedAt`:
> 
> ```ts
> const request = {
>   ...
>   submittedAt: /* ISO 8601 String OR Date object */,
>   ...
> };
> ```

### info

The info object contains all of the relevant LTI parameters that were passed through in the original LTI launch request:

```ts
const info = {
    sourcedId: /* The LTI sourcedid, usually "lis_result_sourcedid" in the original LTI launch request */,
    url: /* The LTI outcome url, usually "lis_outcome_service_url" in the original LTI launch request */,
};
```

### credentials

The credentials object contains the app's consumer credentials:

```ts
const credentials = {
    consumerKey: /* The app's consumer key */,
    consumerSecret: /* The app's shared secret */,
};
```

## Full Example

Sending a passback of 78 points with a "Hello World" text submission. In this example, we have invented a `launchBody` object that contains the body of the original LTI launch request and we created a `secureFile` object that has `getKey` and `getSecret` functions that return the app's consumer key and consumer secret, respectively.

```ts
import sendPassback from 'caccl-grade-passback';

const request = {
    score: 78,
    text: 'Hello World',
};

const info = {
    sourcedId: launchBody.lis_result_sourcedid,
    url: launchBody.lis_outcome_service_url,
};

const credentials = {
    consumerKey: secureFile.getKey(),
    consumerSecret: secureFile.getSecret(),
};

await sendPassback(request, info, credentials);
```