# `Ltix.GradeService.Score`
[🔗](https://github.com/DecoyLex/ltix/blob/main/lib/ltix/grade_service/score.ex#L1)

A score to post to the platform's gradebook.

Scores are write-only — the tool constructs them and POSTs to the
platform. Use `new/1` to build a validated score, then pass it to
`Ltix.GradeService.post_score/3`.

The `grading_progress` must be `:fully_graded` for the platform to
record the score as a final grade. Other values are considered
partial and the platform may ignore them.

## Examples

    {:ok, score} = Ltix.GradeService.Score.new(
      user_id: "12345",
      score_given: 85,
      score_maximum: 100,
      activity_progress: :completed,
      grading_progress: :fully_graded
    )

    score.score_given
    #=> 85

# `t`

```elixir
@type t() :: %Ltix.GradeService.Score{
  activity_progress:
    :initialized | :started | :in_progress | :submitted | :completed,
  comment: binary(),
  extensions: %{optional(binary()) => any()},
  grading_progress:
    :fully_graded | :pending | :pending_manual | :failed | :not_ready,
  score_given: number(),
  score_maximum: number(),
  scoring_user_id: binary(),
  submission: %{optional(atom()) => binary()},
  timestamp: %DateTime{
    calendar: term(),
    day: term(),
    hour: term(),
    microsecond: term(),
    minute: term(),
    month: term(),
    second: term(),
    std_offset: term(),
    time_zone: term(),
    utc_offset: term(),
    year: term(),
    zone_abbr: term()
  },
  user_id: binary()
}
```

# `new`

```elixir
@spec new(keyword()) :: {:ok, t()} | {:error, Exception.t()}
```

Build a validated score from keyword options.

Auto-generates a `timestamp` with microsecond precision if not provided.

## Options

* `:timestamp` (struct of type `DateTime`) - When the score was set. Auto-generated if not provided.

* `:comment` (`t:String.t/0`) - Plain text comment visible to both student and instructor.

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

* `:user_id` (`t:String.t/0`) - Required. LTI user ID of the score recipient.

* `:activity_progress` (`"initialized"` | `"started"` | `"in_progress"` | `"submitted"` | `"completed"`) - Required. User's progress toward completing the activity.

* `:grading_progress` (`"fully_graded"` | `"pending"` | `"pending_manual"` | `"failed"` | `"not_ready"`) - Required. Status of the grading process. Must be `:fully_graded` for final scores.

* `:score_given` (`t:number/0`) - Score value (must be >= 0). Requires `score_maximum` when present.

* `:score_maximum` (`t:number/0`) - Maximum possible score (must be > 0). Required when `score_given` is present.

* `:scoring_user_id` (`t:String.t/0`) - LTI user ID of the person who provided the score.

* `:submission` (`t:map/0`) - Submission metadata with `:started_at` and `:submitted_at` ISO 8601 timestamps.

## Examples

    iex> {:ok, score} = Ltix.GradeService.Score.new(user_id: "u1", activity_progress: :completed, grading_progress: :fully_graded)
    iex> score.user_id
    "u1"

Strings are also accepted for `activity_progress` and `grading_progress`,
which is convenient when values come from form params:

    iex> {:ok, score} = Ltix.GradeService.Score.new(user_id: "u1", activity_progress: "completed", grading_progress: "fully_graded")
    iex> score.activity_progress
    :completed

# `to_json`

```elixir
@spec to_json(t()) :: map()
```

Serialize a score to a JSON-compatible map.

## Examples

    iex> {:ok, score} = Ltix.GradeService.Score.new(user_id: "u1", activity_progress: :completed, grading_progress: :fully_graded, timestamp: ~U[2024-01-15 10:30:00.123456Z])
    iex> json = Ltix.GradeService.Score.to_json(score)
    iex> json["userId"]
    "u1"

---

*Consult [api-reference.md](api-reference.md) for complete listing*