How to Integrate Bolt.new with Blackboard Learn

1# .env — add to project root
2# Your Blackboard Learn instance URL (no trailing slash)
3BLACKBOARD_BASE_URL=https://yourschool.blackboard.com
4# From Blackboard → System Admin → REST API Integrations
5BLACKBOARD_APP_KEY=your_application_key
6BLACKBOARD_APP_SECRET=your_application_secret
7# For three-legged OAuth (user-specific data)
8# Must be your deployed Netlify URL, not the Bolt preview
9BLACKBOARD_REDIRECT_URI=https://your-app.netlify.app/api/blackboard/callback

1// lib/blackboard-client.ts
2interface TokenCache {
3  token: string;
4  expiresAt: number;
5}
6
7let tokenCache: TokenCache | null = null;
8
9async function getAccessToken(): Promise<string> {
10  // Return cached token if still valid (with 60s buffer)
11  if (tokenCache && Date.now() < tokenCache.expiresAt - 60_000) {
12    return tokenCache.token;
13  }
14
15  const baseUrl = process.env.BLACKBOARD_BASE_URL;
16  const appKey = process.env.BLACKBOARD_APP_KEY;
17  const appSecret = process.env.BLACKBOARD_APP_SECRET;
18
19  if (!baseUrl || !appKey || !appSecret) {
20    throw new Error('Blackboard credentials not configured');
21  }
22
23  const credentials = Buffer.from(`${appKey}:${appSecret}`).toString('base64');
24
25  const res = await fetch(`${baseUrl}/learn/api/public/v1/oauth2/token`, {
26    method: 'POST',
27    headers: {
28      Authorization: `Basic ${credentials}`,
29      'Content-Type': 'application/x-www-form-urlencoded',
30    },
31    body: 'grant_type=client_credentials',
32  });
33
34  if (!res.ok) {
35    const error = await res.text();
36    throw new Error(`Blackboard OAuth failed: ${res.status} ${error}`);
37  }
38
39  const { access_token, expires_in } = await res.json();
40
41  tokenCache = {
42    token: access_token,
43    expiresAt: Date.now() + expires_in * 1000,
44  };
45
46  return access_token;
47}
48
49export async function blackboardRequest<T>(
50  endpoint: string,
51  options: RequestInit = {}
52): Promise<T> {
53  const baseUrl = process.env.BLACKBOARD_BASE_URL;
54  const token = await getAccessToken();
55
56  const res = await fetch(`${baseUrl}/learn/api/public${endpoint}`, {
57    ...options,
58    headers: {
59      Authorization: `Bearer ${token}`,
60      'Content-Type': 'application/json',
61      ...options.headers,
62    },
63  });
64
65  if (!res.ok) {
66    const error = await res.json().catch(() => ({ message: res.statusText }));
67    throw new Error(`Blackboard API error ${res.status}: ${JSON.stringify(error)}`);
68  }
69
70  return res.json();
71}
72
73// app/api/blackboard/courses/route.ts
74import { NextResponse } from 'next/server';
75import { blackboardRequest } from '@/lib/blackboard-client';
76
77interface BlackboardCourse {
78  id: string;
79  courseId: string;
80  name: string;
81  description?: string;
82  created?: string;
83  availability?: { available: string };
84}
85
86export async function GET(request: Request) {
87  try {
88    const { searchParams } = new URL(request.url);
89    const limit = searchParams.get('limit') || '50';
90    const offset = searchParams.get('offset') || '0';
91
92    const data = await blackboardRequest<{ results: BlackboardCourse[] }>(
93      `/v3/courses?limit=${limit}&offset=${offset}`
94    );
95
96    return NextResponse.json({
97      courses: data.results.map(c => ({
98        id: c.id,
99        courseId: c.courseId,
100        name: c.name,
101        isAvailable: c.availability?.available === 'Yes',
102        created: c.created,
103      })),
104    });
105  } catch (error) {
106    const message = error instanceof Error ? error.message : 'Failed to fetch courses';
107    return NextResponse.json({ error: message }, { status: 500 });
108  }
109}

1// app/api/blackboard/grades/[userId]/route.ts
2import { NextResponse } from 'next/server';
3import { blackboardRequest } from '@/lib/blackboard-client';
4
5function scoreToLetter(percentage: number): string {
6  if (percentage >= 90) return 'A';
7  if (percentage >= 80) return 'B';
8  if (percentage >= 70) return 'C';
9  if (percentage >= 60) return 'D';
10  return 'F';
11}
12
13interface GradeEntry {
14  columnId: string;
15  status?: string;
16  score?: { given: number; possible: number };
17  gradeValue?: string;
18  text?: string;
19}
20
21interface CourseResult {
22  courseId: { id: string; courseId: string };
23}
24
25export async function GET(
26  _request: Request,
27  { params }: { params: { userId: string } }
28) {
29  try {
30    const { userId } = params;
31
32    // Fetch user's course memberships
33    const memberships = await blackboardRequest<{ results: CourseResult[] }>(
34      `/v1/users/${userId}/courses?limit=20`
35    );
36
37    const courseGrades = await Promise.all(
38      memberships.results.map(async (membership) => {
39        const course = membership.courseId;
40        try {
41          const grades = await blackboardRequest<{ results: GradeEntry[] }>(
42            `/v2/courses/${course.id}/gradebook/users/${userId}?limit=100`
43          );
44
45          const scoredGrades = grades.results.filter(
46            g => g.score?.given !== undefined && g.score?.possible > 0
47          );
48
49          const totalGiven = scoredGrades.reduce((sum, g) => sum + (g.score?.given || 0), 0);
50          const totalPossible = scoredGrades.reduce((sum, g) => sum + (g.score?.possible || 0), 0);
51          const percentage = totalPossible > 0 ? (totalGiven / totalPossible) * 100 : 0;
52
53          return {
54            courseId: course.courseId,
55            courseName: course.courseId, // Fetch course name separately if needed
56            percentage: Math.round(percentage),
57            letterGrade: scoreToLetter(percentage),
58            gradedItems: scoredGrades.length,
59            gradeItems: grades.results.map(g => ({
60              columnId: g.columnId,
61              status: g.status,
62              given: g.score?.given,
63              possible: g.score?.possible,
64              displayGrade: g.gradeValue || g.text || 'Not graded',
65            })),
66          };
67        } catch {
68          // Some courses may not have gradebook access
69          return null;
70        }
71      })
72    );
73
74    return NextResponse.json({
75      grades: courseGrades.filter(Boolean),
76    });
77  } catch (error) {
78    const message = error instanceof Error ? error.message : 'Failed to fetch grades';
79    return NextResponse.json({ error: message }, { status: 500 });
80  }
81}

1// app/api/blackboard/auth/route.ts
2import { NextResponse } from 'next/server';
3import { cookies } from 'next/headers';
4import crypto from 'crypto';
5
6export async function GET() {
7  const state = crypto.randomBytes(16).toString('hex');
8  const baseUrl = process.env.BLACKBOARD_BASE_URL;
9  const appKey = process.env.BLACKBOARD_APP_KEY;
10  const redirectUri = process.env.BLACKBOARD_REDIRECT_URI;
11
12  // Store state in cookie for CSRF protection
13  cookies().set('bb_oauth_state', state, {
14    httpOnly: true,
15    secure: process.env.NODE_ENV === 'production',
16    maxAge: 600, // 10 minutes
17  });
18
19  const params = new URLSearchParams({
20    client_id: appKey!,
21    response_type: 'code',
22    redirect_uri: redirectUri!,
23    scope: 'read',
24    state,
25  });
26
27  const authUrl = `${baseUrl}/learn/api/public/v1/oauth2/authorizationcode?${params}`;
28  return NextResponse.redirect(authUrl);
29}
30
31// app/api/blackboard/callback/route.ts
32import { NextResponse } from 'next/server';
33import { cookies } from 'next/headers';
34
35export async function GET(request: Request) {
36  const { searchParams } = new URL(request.url);
37  const code = searchParams.get('code');
38  const state = searchParams.get('state');
39  const storedState = cookies().get('bb_oauth_state')?.value;
40
41  if (!code || state !== storedState) {
42    return NextResponse.json({ error: 'Invalid OAuth state' }, { status: 400 });
43  }
44
45  const baseUrl = process.env.BLACKBOARD_BASE_URL;
46  const appKey = process.env.BLACKBOARD_APP_KEY;
47  const appSecret = process.env.BLACKBOARD_APP_SECRET;
48  const redirectUri = process.env.BLACKBOARD_REDIRECT_URI;
49
50  const credentials = Buffer.from(`${appKey}:${appSecret}`).toString('base64');
51
52  const tokenRes = await fetch(`${baseUrl}/learn/api/public/v1/oauth2/token`, {
53    method: 'POST',
54    headers: {
55      Authorization: `Basic ${credentials}`,
56      'Content-Type': 'application/x-www-form-urlencoded',
57    },
58    body: new URLSearchParams({
59      grant_type: 'authorization_code',
60      code: code!,
61      redirect_uri: redirectUri!,
62    }),
63  });
64
65  const tokenData = await tokenRes.json();
66
67  // Store access token in an HttpOnly cookie
68  const response = NextResponse.redirect(new URL('/dashboard', request.url));
69  response.cookies.set('bb_access_token', tokenData.access_token, {
70    httpOnly: true,
71    secure: process.env.NODE_ENV === 'production',
72    maxAge: tokenData.expires_in,
73  });
74
75  return response;
76}