blackboard-upc 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to `blackboard-upc` will be documented here.
+
+---
+
+## [1.0.0] — 2026-03-30
+
+### Added
+
+#### Autenticación
+- Login via **SAML SSO → Microsoft Azure AD** con Playwright (ventana del browser)
+- Sesión persistida en `~/.blackboard-cli/session.json` (TTL 8h, permisos 600)
+- Comandos `login`, `logout`, `whoami`, `status`
+
+#### Cursos
+- `courses list` — cursos inscritos con nombre, rol, estado y último acceso
+- `courses get <id>` — detalle de un curso
+- `courses contents <id>` — árbol de contenido navegable por carpetas
+- `courses contents --type file|folder|assignment|document` — filtro por tipo
+- `courses announcements <id>` — anuncios del curso
+- `courses grades <id>` — notas del ciclo
+
+#### Tareas
+- `assignments list <id>` — tareas con fecha de entrega, nota actual y alertas de color
+- `assignments list --pending` — solo las pendientes de entrega
+- `assignments attempts <id> <columnId>` — historial de entregas
+- `assignments submit` — entregar tarea con archivo (`-f`), texto (`-t`) o borrador (`--draft`)
+
+#### Descargas
+- `download <courseId> <contentId>` — descargar archivo adjunto individual
+- `download-folder <courseId> <folderId>` — descarga recursiva de toda una carpeta
+- `download-folder --filter <keyword>` — filtrar por nombre de archivo
+
+#### API & Developer experience
+- `api <METHOD> <path>` — passthrough a cualquier endpoint de la REST API
+- `endpoints` — catálogo documentado de 22+ endpoints con parámetros
+- Todos los comandos aceptan `--json` con spinners redirigidos a `stderr`
+
+#### MCP Server
+- Comando `mcp` — inicia un servidor MCP (stdio) para Claude Code y Claude Desktop
+- 13 herramientas: `whoami`, `list_courses`, `get_course`, `list_contents`,
+  `list_announcements`, `list_assignments`, `list_attempts`, `get_grades`,
+  `list_attachments`, `download_attachment`, `submit_attempt`, `raw_api`, `system_version`
+- `CLAUDE.md` — guía de comportamiento para agentes IA
+
+#### UI
+- Banner ASCII con color rojo UPC (`#E31837`)
+- Prompt "¿Qué puedo hacer ahora?" tras login exitoso
+- Paleta semántica: `ok` (verde), `fail` (rojo), `warn` (amarillo), `hint` (cyan)
+
+---
+
+## Roadmap
+
+- [ ] `npx` install sin clonar repo (publicación en npm)
+- [ ] Refresh automático de sesión antes de expirar
+- [ ] Notificaciones de entregas próximas (`assignments due`)
+- [ ] Descarga de videos de grabaciones de clase
+- [ ] Soporte para múltiples cuentas / ciclos simultáneos

package/CLAUDE.md

@@ -0,0 +1,70 @@
+# blackboard-cli — Agent Guide
+
+This CLI gives Claude direct access to UPC Aula Virtual (Blackboard Learn). Use it to help students check their courses, assignments, grades, and download materials — all without opening a browser.
+
+## Setup
+
+Before using any tool, the user must be authenticated:
+
+```bash
+blackboard login        # opens browser for Microsoft SSO
+blackboard whoami       # verify session is active
+```
+
+If you get `Not authenticated`, ask the user to run `blackboard login`.
+
+## Primary workflow
+
+```
+1. list_courses                           → find the relevant courseId
+2. list_assignments <courseId>            → see pending tasks + due dates
+3. get_grades <courseId>                  → check current grades
+4. list_contents <courseId>               → browse course materials
+5. list_contents <courseId> <parentId>    → navigate into a subfolder
+6. list_attachments <courseId> <contentId>→ find downloadable files
+```
+
+## Agent behavior rules
+
+- **Always confirm before submitting** (`submit_attempt`). Show the user what will be submitted and ask for confirmation. Never submit silently.
+- **Show grades in context** — when showing grades, also show the assignment name, max score, and due date if available.
+- **Navigate content recursively** — if the user asks for materials, explore subfolders using `list_contents` with `parentId`.
+- **Use `raw_api` for anything not covered** — the Blackboard REST API is extensive. If there's no specific tool, use `raw_api` with the correct endpoint.
+- **Session errors are recoverable** — if you get a session error, tell the user to run `blackboard login` (not a fatal error).
+- **Respect rate limits** — don't fan out more than 5 parallel API calls.
+
+## Key IDs
+
+Course IDs look like `_529580_1`. Content and column IDs follow the same pattern.
+
+## Useful endpoints (via raw_api)
+
+```
+GET /learn/api/public/v1/users/me
+GET /learn/api/public/v1/users/{userId}/courses
+GET /learn/api/public/v1/courses/{courseId}/contents
+GET /learn/api/public/v1/courses/{courseId}/contents/{id}/children
+GET /learn/api/public/v1/courses/{courseId}/announcements
+GET /learn/api/public/v2/courses/{courseId}/gradebook/columns
+GET /learn/api/public/v2/courses/{courseId}/gradebook/columns/{id}/attempts
+GET /learn/api/public/v1/courses/{courseId}/contents/{id}/attachments
+GET /learn/api/public/v1/courses/{courseId}/contents/{id}/attachments/{id}/download
+```
+
+## MCP tools available
+
+| Tool | What it does |
+|------|-------------|
+| `whoami` | Current student info |
+| `system_version` | Server version |
+| `list_courses` | All enrolled courses |
+| `get_course` | Single course details |
+| `list_contents` | Course materials tree |
+| `list_announcements` | Course announcements |
+| `list_assignments` | Tasks with due dates + grades |
+| `list_attempts` | Submission history |
+| `get_grades` | Full grade report for a course |
+| `list_attachments` | Files in a content item |
+| `download_attachment` | Download file (base64) |
+| `submit_attempt` | Submit assignment (confirm first!) |
+| `raw_api` | Any other Blackboard endpoint |

package/README.md

@@ -0,0 +1,222 @@
+# blackboard-cli
+
+> Accede a **UPC Aula Virtual** desde la terminal — sin abrir el navegador.
+
+CLI no oficial para estudiantes de la UPC. Consulta cursos, descarga materiales, revisa tareas y entregas directamente desde la línea de comandos. También expone un **servidor MCP** para que Claude lo use como herramientas nativas.
+
+```bash
+npx blackboard-upc login
+```
+
+---
+
+## Instalación
+
+```bash
+# Opción 1 — usar directamente con npx (sin instalar)
+npx blackboard-upc login
+
+# Opción 2 — instalar globalmente
+npm install -g blackboard-upc
+blackboard login
+
+# Opción 3 — clonar el repo
+git clone https://github.com/aleoroni/blackboard-cli
+cd blackboard-cli
+npm install
+npx playwright install chromium
+node run.js login
+```
+
+---
+
+## Primeros pasos
+
+### 1. Login
+
+```bash
+blackboard login
+```
+
+Se abre una ventana del navegador con el login de Microsoft UPC. Inicia sesión con tu cuenta `u20XXXXXXX@upc.edu.pe` (incluye MFA si lo tienes). La ventana se cierra sola y la sesión queda guardada 8 horas.
+
+```
+  ██████  ██       █████   ██████ ██   ██ ██████   ██████   █████  ██████  ██████
+  ...
+  CLI no oficial para UPC Aula Virtual · Blackboard Learn
+
+  ✓ Sesión guardada — expira en 8 horas
+    Usuario: Alejandro Daniel Oroncoy Almeyda
+
+  ¿Qué puedo hacer ahora?
+
+  blackboard courses list                ver tus cursos del ciclo
+  blackboard assignments list <id>       ver tareas pendientes y notas
+  blackboard courses contents <id>       explorar materiales
+  blackboard download-folder <id> <fid>  descargar toda una carpeta
+```
+
+### 2. Ver cursos y tareas
+
+```bash
+blackboard courses list
+
+  _529630_1  Fundamentos de Arquitectura de Software [Ultra]
+  _529580_1  Finanzas e Ingeniería Económica [Ultra]
+  _529533_1  Desarrollo de Soluciones IOT [Ultra]
+  _529760_1  Diseño de Experimentos de Ingeniería de Software [Ultra]
+
+blackboard assignments list _529760_1
+
+  _13890556_1  Tarea 1  [manual]
+    Nota: sin entregar · Máx: 3 pts · Entrega: 05/03/2026 (vencida hace 23d)
+```
+
+---
+
+## Comandos
+
+### Sesión
+```bash
+blackboard login              # autenticación Microsoft SSO
+blackboard logout             # borrar sesión
+blackboard whoami             # usuario activo y tiempo restante
+blackboard status             # versión del servidor Blackboard
+```
+
+### Cursos
+```bash
+blackboard courses list
+blackboard courses get <courseId>
+blackboard courses contents <courseId>
+blackboard courses contents <courseId> --parent <folderId>   # navegar subcarpetas
+blackboard courses contents <courseId> --type file|folder|assignment
+blackboard courses announcements <courseId>
+blackboard courses grades <courseId>
+```
+
+### Tareas
+```bash
+blackboard assignments list <courseId>              # tareas con nota y fecha
+blackboard assignments list <courseId> --pending    # solo pendientes
+blackboard assignments attempts <courseId> <id>     # historial de entregas
+blackboard assignments submit <courseId> <id> -f tarea.pdf
+blackboard assignments submit <courseId> <id> -t "Mi respuesta" -c "Comentario"
+blackboard assignments submit <courseId> <id> -f borrador.pdf --draft
+```
+
+### Descargas
+```bash
+blackboard download <courseId> <contentId>                    # archivo individual
+blackboard download-folder <courseId> <folderId> -o ./dir/    # carpeta completa
+blackboard download-folder <courseId> <folderId> --filter "parcial"
+```
+
+### API raw / scripting
+```bash
+blackboard api GET /learn/api/public/v1/users/me
+blackboard api GET /learn/api/public/v1/courses -q "limit=10"
+blackboard endpoints          # catálogo de todos los endpoints conocidos
+blackboard endpoints --json   # para pipelines
+```
+
+Todos los comandos aceptan `--json`. Los spinners van a `stderr`, por lo que `--json 2>/dev/null` es JSON limpio.
+
+---
+
+## Uso con Claude (MCP)
+
+`blackboard-cli` incluye un servidor MCP que Claude puede usar como herramientas nativas.
+
+### Claude Code
+
+Añade a `.mcp.json` en tu proyecto:
+
+```json
+{
+  "mcpServers": {
+    "blackboard": {
+      "command": "npx",
+      "args": ["blackboard-upc", "mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Edita `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "blackboard": {
+      "command": "npx",
+      "args": ["blackboard-upc", "mcp"]
+    }
+  }
+}
+```
+
+> **Nota:** Si usas instalación global, reemplaza `npx blackboard-upc` por la ruta absoluta del binario (`which blackboard`).
+
+### Herramientas MCP disponibles
+
+| Herramienta | Descripción |
+|---|---|
+| `whoami` | Info del estudiante autenticado |
+| `list_courses` | Cursos inscritos |
+| `get_course` | Detalle de un curso |
+| `list_contents` | Árbol de materiales |
+| `list_announcements` | Anuncios del curso |
+| `list_assignments` | Tareas con fechas y notas |
+| `list_attempts` | Historial de entregas |
+| `get_grades` | Notas del ciclo |
+| `list_attachments` | Archivos de un contenido |
+| `download_attachment` | Descargar archivo (base64) |
+| `submit_attempt` | Entregar tarea (pide confirmación) |
+| `raw_api` | Cualquier endpoint de Blackboard |
+
+Con Claude puedes hacer cosas como:
+
+> *"¿Qué tareas tengo pendientes esta semana?"*
+> *"Descárgame todos los exámenes del curso de Finanzas"*
+> *"¿Cuál es mi nota actual en Arquitectura de Software?"*
+
+---
+
+## Cómo funciona la autenticación
+
+UPC usa **SAML SSO → Microsoft Azure AD**. El CLI:
+1. Abre Chromium (Playwright) en la URL SAML de UPC
+2. Te muestra el login de Microsoft — tú ingresas tus credenciales
+3. Captura las cookies de sesión automáticamente al redirigir a `/ultra`
+4. Guarda todo en `~/.blackboard-cli/session.json` (permisos `600`)
+
+La sesión dura **8 horas**. Después necesitas volver a hacer `login`.
+
+---
+
+## Stack
+
+- **TypeScript** + `tsx` — sin build step
+- **Playwright** — maneja el flujo SAML/SSO
+- **Axios** — llamadas a la REST API con cookies de sesión
+- **Commander.js** — framework CLI
+- **MCP SDK** — servidor para Claude
+- **Chalk** + **Ora** — output en la terminal
+
+---
+
+## Notas
+
+- Probado con Blackboard Learn `v4000.10.0` (UPC, 2026).
+- CLI **no oficial** — sin afiliación con UPC ni Blackboard Inc.
+- Úsalo solo con tu propia cuenta. Respeta los TOS de UPC.
+- Las cookies se guardan localmente. No se envían a servidores externos.
+
+---
+
+## Licencia
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "blackboard-upc",
+  "version": "1.0.0",
+  "description": "CLI no oficial para UPC Aula Virtual (Blackboard Learn) — acceso desde la terminal y MCP para Claude",
+  "main": "run.js",
+  "bin": {
+    "blackboard": "./run.js",
+    "blackboard-upc": "./run.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "blackboard",
+    "upc",
+    "aula-virtual",
+    "cli",
+    "mcp",
+    "claude",
+    "lms",
+    "peru"
+  ],
+  "author": "Alejandro Oroncoy",
+  "homepage": "https://github.com/aleoroni/blackboard-cli",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aleoroni/blackboard-cli.git"
+  },
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^22.0.0",
+    "axios": "^1.7.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "form-data": "^4.0.5",
+    "inquirer": "^10.1.0",
+    "ora": "^8.1.0",
+    "playwright": "^1.47.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "zod": "^4.3.6"
+  }
+}

package/run.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Run TypeScript directly without build step
+const { spawnSync } = require('child_process');
+const path = require('path');
+const tsx = path.join(__dirname, 'node_modules', '.bin', 'tsx');
+const entry = path.join(__dirname, 'src', 'index.ts');
+const result = spawnSync(tsx, [entry, ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exit(result.status ?? 0);

package/src/api/assignments.ts

@@ -0,0 +1,135 @@
+import type { AxiosInstance } from 'axios';
+import fs from 'fs';
+import path from 'path';
+import FormData from 'form-data';
+
+export interface GradeColumn {
+  id: string;
+  name: string;
+  contentId?: string;
+  score?: { possible: number };
+  availability?: { available: string };
+  grading?: {
+    type: 'Attempts' | 'Manual' | 'Calculated';
+    due?: string;
+    attemptsAllowed?: number;
+    scoringModel?: string;
+  };
+  gradebookCategoryId?: string;
+  scoreProviderHandle?: string;
+  includeInCalculations?: boolean;
+}
+
+export interface Attempt {
+  id: string;
+  userId?: string;
+  status: string;
+  displayGrade?: { score?: number; text?: string };
+  score?: number;
+  text?: string;
+  studentComments?: string;
+  studentSubmission?: string;
+  created?: string;
+  modified?: string;
+  attemptDate?: string;
+  files?: Array<{ id: string; fileName: string; mimeType: string }>;
+}
+
+export interface SubmitAttemptBody {
+  studentComments?: string;
+  studentSubmission?: string;
+  fileUploadIds?: string[];
+  status?: string;
+}
+
+export async function listAssignments(
+  client: AxiosInstance,
+  courseId: string
+): Promise<GradeColumn[]> {
+  const r = await client.get(`/learn/api/public/v2/courses/${courseId}/gradebook/columns`, {
+    params: { limit: 100 },
+  });
+  // Only return Attempts and Manual columns (student-relevant)
+  return (r.data.results as GradeColumn[]).filter(
+    (c) => c.grading?.type === 'Attempts' || c.grading?.type === 'Manual'
+  );
+}
+
+export async function getAssignment(
+  client: AxiosInstance,
+  courseId: string,
+  columnId: string
+): Promise<GradeColumn> {
+  const r = await client.get(`/learn/api/public/v2/courses/${courseId}/gradebook/columns/${columnId}`);
+  return r.data;
+}
+
+export async function listAttempts(
+  client: AxiosInstance,
+  courseId: string,
+  columnId: string
+): Promise<Attempt[]> {
+  const r = await client.get(
+    `/learn/api/public/v2/courses/${courseId}/gradebook/columns/${columnId}/attempts`,
+    { params: { limit: 20 } }
+  );
+  return r.data.results;
+}
+
+export async function getAttempt(
+  client: AxiosInstance,
+  courseId: string,
+  columnId: string,
+  attemptId: string
+): Promise<Attempt> {
+  const r = await client.get(
+    `/learn/api/public/v2/courses/${courseId}/gradebook/columns/${columnId}/attempts/${attemptId}`
+  );
+  return r.data;
+}
+
+export async function uploadFile(
+  client: AxiosInstance,
+  filePath: string
+): Promise<string> {
+  const fileName = path.basename(filePath);
+  const fileBuffer = fs.readFileSync(filePath);
+
+  const form = new FormData();
+  form.append('file', fileBuffer, {
+    filename: fileName,
+    contentType: 'application/octet-stream',
+  });
+
+  const r = await client.post('/learn/api/public/v1/uploads', form, {
+    headers: {
+      ...form.getHeaders(),
+    },
+  });
+  return r.data.id as string;
+}
+
+export async function submitAttempt(
+  client: AxiosInstance,
+  courseId: string,
+  columnId: string,
+  body: SubmitAttemptBody
+): Promise<Attempt> {
+  const r = await client.post(
+    `/learn/api/public/v2/courses/${courseId}/gradebook/columns/${columnId}/attempts`,
+    { ...body, status: body.status ?? 'NeedsGrading' }
+  );
+  return r.data;
+}
+
+export async function getMyGrade(
+  client: AxiosInstance,
+  courseId: string,
+  columnId: string,
+  userId: string
+): Promise<any> {
+  const r = await client.get(
+    `/learn/api/public/v1/courses/${courseId}/gradebook/users/${userId}/columns/${columnId}`
+  );
+  return r.data;
+}

package/src/api/client.ts

@@ -0,0 +1,41 @@
+import axios, { AxiosInstance, AxiosError } from 'axios';
+import type { Session } from '../types/index.js';
+
+const BASE_URL = 'https://aulavirtual.upc.edu.pe';
+
+export function createClient(session: Session): AxiosInstance {
+  // Build cookie header string
+  const cookieStr = session.cookies
+    .filter((c) => {
+      const domain = c.domain.replace(/^\./, '');
+      return 'aulavirtual.upc.edu.pe'.endsWith(domain) || domain === 'aulavirtual.upc.edu.pe';
+    })
+    .map((c) => `${c.name}=${c.value}`)
+    .join('; ');
+
+  const client = axios.create({
+    baseURL: BASE_URL,
+    headers: {
+      Cookie: cookieStr,
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      ...(session.xsrfToken ? { 'X-Blackboard-XSRF': session.xsrfToken } : {}),
+    },
+    withCredentials: true,
+  });
+
+  // Intercept 401 to give a helpful message
+  client.interceptors.response.use(
+    (r) => r,
+    (err: AxiosError) => {
+      if (err.response?.status === 401) {
+        const e = new Error('Session expired. Run: blackboard login');
+        (e as any).code = 'SESSION_EXPIRED';
+        throw e;
+      }
+      throw err;
+    }
+  );
+
+  return client;
+}

package/src/api/courses.ts

@@ -0,0 +1,110 @@
+import type { AxiosInstance } from 'axios';
+import type { Course, UserCourse, PaginatedResponse } from '../types/index.js';
+
+export async function getMe(client: AxiosInstance): Promise<any> {
+  const r = await client.get('/learn/api/public/v1/users/me');
+  return r.data;
+}
+
+export async function getMyCourses(
+  client: AxiosInstance,
+  userId: string,
+  opts: { limit?: number; offset?: number } = {}
+): Promise<PaginatedResponse<UserCourse & { course?: Course }>> {
+  const params: Record<string, any> = { limit: opts.limit ?? 50 };
+  if (opts.offset) params.offset = opts.offset;
+
+  const r = await client.get(`/learn/api/public/v1/users/${userId}/courses`, { params });
+  const memberships: UserCourse[] = r.data.results;
+
+  // Resolve course names in parallel
+  const courseDetails = await Promise.allSettled(
+    memberships.map((m) => getCourse(client, m.courseId))
+  );
+
+  const results = memberships.map((m, i) => ({
+    ...m,
+    course: courseDetails[i].status === 'fulfilled' ? courseDetails[i].value : undefined,
+  }));
+
+  return { results, paging: r.data.paging };
+}
+
+export async function getCourse(client: AxiosInstance, courseId: string): Promise<Course> {
+  const r = await client.get(`/learn/api/public/v1/courses/${courseId}`);
+  return r.data;
+}
+
+export async function listCourses(
+  client: AxiosInstance,
+  opts: { limit?: number; offset?: number } = {}
+): Promise<PaginatedResponse<Course>> {
+  const r = await client.get('/learn/api/public/v1/courses', {
+    params: { limit: opts.limit ?? 50, offset: opts.offset ?? 0 },
+  });
+  return r.data;
+}
+
+export async function getCourseContents(
+  client: AxiosInstance,
+  courseId: string,
+  parentId?: string
+): Promise<PaginatedResponse<any>> {
+  const path = parentId
+    ? `/learn/api/public/v1/courses/${courseId}/contents/${parentId}/children`
+    : `/learn/api/public/v1/courses/${courseId}/contents`;
+  const r = await client.get(path, {
+    params: {
+      limit: 100,
+      fields: 'id,parentId,title,body,created,modified,position,hasChildren,launchInNewWindow,availability,contentHandler',
+    },
+  });
+  return r.data;
+}
+
+export async function getCourseAnnouncements(
+  client: AxiosInstance,
+  courseId: string
+): Promise<PaginatedResponse<any>> {
+  const r = await client.get(`/learn/api/public/v1/courses/${courseId}/announcements`, {
+    params: { limit: 20 },
+  });
+  return r.data;
+}
+
+export async function getGradeColumns(
+  client: AxiosInstance,
+  courseId: string
+): Promise<PaginatedResponse<any>> {
+  const r = await client.get(`/learn/api/public/v1/courses/${courseId}/gradebook/columns`, {
+    params: { limit: 50 },
+  });
+  return r.data;
+}
+
+export async function getGrades(
+  client: AxiosInstance,
+  courseId: string,
+  userId: string
+): Promise<PaginatedResponse<any>> {
+  const r = await client.get(
+    `/learn/api/public/v1/courses/${courseId}/gradebook/users/${userId}`,
+    { params: { limit: 50 } }
+  );
+  return r.data;
+}
+
+export async function getCourseMemberships(
+  client: AxiosInstance,
+  courseId: string
+): Promise<PaginatedResponse<any>> {
+  const r = await client.get(`/learn/api/public/v1/courses/${courseId}/users`, {
+    params: { limit: 100 },
+  });
+  return r.data;
+}
+
+export async function getSystemVersion(client: AxiosInstance): Promise<any> {
+  const r = await client.get('/learn/api/public/v1/system/version');
+  return r.data;
+}