@spec authenticate(
  Ltix.LaunchContext.t() | Ltix.Registration.t(),
  keyword()
) :: {:ok, Ltix.OAuth.Client.t()} | {:error, Exception.t()}

Acquire an OAuth token for the grade service.

Accepts a %LaunchContext{} or a %Registration{}. With a launch context, the endpoint and scopes are extracted from the AGS claim. With a registration, pass the endpoint via the :endpoint option.

From a launch context

{:ok, client} = Ltix.GradeService.authenticate(launch_context)

From a registration

{:ok, client} = Ltix.GradeService.authenticate(registration,
  endpoint: %AgsEndpoint{
    lineitems: "https://lms.example.com/lineitems",
    scope: ["https://purl.imsglobal.org/spec/lti-ags/scope/lineitem"]
  }
)

Options (launch context)

• :req_options (keyword/0) - Options passed through to Req.request/2. The default value is [].

Options (registration)

• :endpoint (struct of type Ltix.LaunchClaims.AgsEndpoint) - Required. AGS endpoint struct.

• :req_options (keyword/0) - Options passed through to Req.request/2. The default value is [].

@spec authenticate!(
  Ltix.LaunchContext.t() | Ltix.Registration.t(),
  keyword()
) :: Ltix.OAuth.Client.t()

Same as authenticate/2 but raises on error.

@spec create_line_item(
  Ltix.OAuth.Client.t(),
  keyword()
) :: {:ok, Ltix.GradeService.LineItem.t()} | {:error, Exception.t()}

Create a new line item.

Options

• :label (String.t/0) - Required. Human-readable label.

• :score_maximum (number/0) - Required. Maximum score (must be > 0).

• :resource_link_id (String.t/0) - Bind to a resource link.

• :resource_id (String.t/0) - Tool's resource identifier.

• :tag (String.t/0) - Qualifier tag.

• :start_date_time (String.t/0) - ISO 8601 with timezone.

• :end_date_time (String.t/0) - ISO 8601 with timezone.

• :grades_released (boolean/0) - Hint about releasing grades.

• :extensions (map/0) - Extension properties keyed by fully qualified URLs. The default value is %{}.

@spec delete_line_item(
  Ltix.OAuth.Client.t(),
  Ltix.GradeService.LineItem.t() | String.t(),
  keyword()
) ::
  :ok | {:error, Exception.t()}

Delete a line item.

Accepts a %LineItem{} struct or a URL string. Returns :ok on success.

By default, refuses to delete the platform-coupled line item (the lineitem URL from the launch claim). Pass force: true to override.

Options

• :force (boolean/0) - Delete even if this is the coupled line item from the launch claim. The default value is false.

@spec get_line_item(
  Ltix.OAuth.Client.t(),
  keyword()
) :: {:ok, Ltix.GradeService.LineItem.t()} | {:error, Exception.t()}

Fetch a single line item.

Options

• :line_item (String.t/0 | struct of type Ltix.GradeService.LineItem) - Line item URL or struct. Defaults to the endpoint's lineitem.

@spec get_results(
  Ltix.OAuth.Client.t(),
  keyword()
) :: {:ok, [Ltix.GradeService.Result.t()]} | {:error, Exception.t()}

Fetch results for a line item.

GETs {lineitem}/results. Follows all rel="next" pagination links and returns a list of %Result{} structs.

Options

• :line_item (String.t/0 | struct of type Ltix.GradeService.LineItem) - Line item URL or struct. Defaults to the endpoint's lineitem.

• :user_id (String.t/0) - Filter results to a single user.

• :per_page (integer/0) - Page size hint.

@spec list_line_items(
  Ltix.OAuth.Client.t(),
  keyword()
) :: {:ok, [Ltix.GradeService.LineItem.t()]} | {:error, Exception.t()}

Fetch all line items from the container endpoint.

Follows all rel="next" pagination links and returns a flat list of %LineItem{} structs.

Options

• :resource_link_id (String.t/0) - Filter to line items bound to this resource link.

• :resource_id (String.t/0) - Filter by the tool's resource identifier.

• :tag (String.t/0) - Filter by tag.

• :per_page (integer/0) - Page size hint.

@spec post_score(Ltix.OAuth.Client.t(), Ltix.GradeService.Score.t(), keyword()) ::
  :ok | {:error, Exception.t()}

Post a score for a user.

The score is POSTed to {lineitem}/scores. When no :line_item option is given, uses the endpoint's lineitem URL (coupled flow).

Options

• :line_item (String.t/0 | struct of type Ltix.GradeService.LineItem) - Line item URL or struct. Defaults to the endpoint's lineitem.

@spec update_line_item(Ltix.OAuth.Client.t(), Ltix.GradeService.LineItem.t()) ::
  {:ok, Ltix.GradeService.LineItem.t()} | {:error, Exception.t()}

Update a line item.

PUTs the full line item to its id URL. Callers should GET first to avoid overwriting fields they did not intend to change.