Add support for Noticeboards

[zmoog]

Noticeboards contains updates from the school. Staying on top of updates is essentials, so I need to make reading them as effortless as possible.

I want to:

• list the noticeboards
• download the attachments
• use an LLM to summarize the notice (out of scope for this tool)

The Noticeboard API docs are available at https://github.com/Lioydiano/Classeviva-Official-Endpoints/tree/master/Noticeboard

[zmoog]

How to list the Noticeboards

$ curl \
  -H "User-Agent: CVVS/std/4.2.3 Android/12" \
  -H "Z-Dev-Apikey: Tg1NWEwNGIgIC0K" \
  -H "Z-Auth-Token: $CLASSEVIVA_TOKEN" \
  https://web.spaggiari.eu/rest/v1/students/$CLASSEVIVA_STUDENT_ID/noticeboard/ | jq 

{
  "items": [
    {
      "pubId": 20135156,
      "pubDT": "2024-03-08T16:48:36+01:00",
      "readStatus": false,
      "evtCode": "CF",
      "cntId": 7694771,
      "cntValidFrom": "2024-03-08",
      "cntValidTo": "2024-04-23",
      "cntValidInRange": true,
      "cntStatus": "active",
      "cntTitle": "CIRC. 298 - SIMULAZIONE PRIMA PROVA ESAME DI STATO ",
      "cntCategory": "Circolare",
      "cntHasChanged": false,
      "cntHasAttach": true,
      "needJoin": false,
      "needReply": false,
      "needFile": false,
      "needSign": false,
      "evento_id": "7694771",
      "dinsert_allegato": "2024-03-08 16:48:32",
      "attachments": [
        {
          "fileName": "298_Simulazione prima prova Esame di Stato.pdf",
          "attachNum": 1
        }
      ]
    },

[zmoog]

The current spaggiari package at https://github.com/zmoog/classeviva/tree/main/adapters/spaggiari doesn't make easy to add support to another service alongside grades.

I need to refactor the grade code into a component (GradeReceiver?) to make add more components more manageable.

[zmoog]

To download the noticeboards attachment, we need two API calls.

First, we need to set the attachment as "read", and then we can download it:

POST v1/students/{studentId}/noticeboard/read/{eventCode}/{pubId}/101
GET v1/students/{studentId}/noticeboard/attach/{eventCode}/{pubId}/101

[zmoog]

A quick test on Postman resulted successful!

[zmoog]

To download an attachment, need to GET the following resource:

https://web.spaggiari.eu/rest/v1/students/<student-id>/noticeboard/attach/CF/<pub-id>/<sequence-number>

For example, given the following noticeboard:

       {
            "pubId": 13863460,
            "pubDT": "2024-01-09T14:36:39+01:00",
            "readStatus": true,
            "evtCode": "CF",
            "cntId": 5107079,
            "cntValidFrom": "2024-01-09",
            "cntValidTo": "2024-05-31",
            "cntValidInRange": true,
            "cntStatus": "active",
            "cntTitle": "CIRC. 221 - PROGETTO CITIES GAMES",
            "cntCategory": "Circolare",
            "cntHasChanged": false,
            "cntHasAttach": true,
            "needJoin": false,
            "needReply": false,
            "needFile": false,
            "needSign": false,
            "evento_id": "5107079",
            "dinsert_allegato": "2024-01-09 14:36:38",
            "attachments": [
                {
                    "fileName": "221_1_Programma per scuole.pdf",
                    "attachNum": 1
                },
                {
                    "fileName": "221_PROGETTO CITIES GAMES.pdf",
                    "attachNum": 2
                }
            ]
        }

Here are the HTTP requests to download the two attachments:

https://web.spaggiari.eu/rest/v1/students/11111/noticeboard/attach/CF/13863460/1
https://web.spaggiari.eu/rest/v1/students/11111/noticeboard/attach/CF/13863460/2

[zmoog]

Classeviva does not allow download of unread noticeboard items. So the next step is to set an item as read before downloading it.

The endpoint to set the read status is:

POST v1/students/{studentId}/noticeboard/read/{eventCode}/{pubId}

--- request
POST https://web.spaggiari.eu/rest/v1/students/123/noticeboard/read/CF/23088634
<no body>

--- response
{
    "item": {
        "title": "CIRC. 353 - ORGANIZZAZIONE ATTIVITA' DIDATTICA 11 E 12 APRILE 2024 ",
        "text": "CIRC. 353 - ORGANIZZAZIONE ATTIVITA' DIDATTICA 11 E 12 APRILE 2024 "
    }
}