@lti-tool/core 0.9.0 → 0.11.0

package/src/schemas/lti13/ags/result.schema.ts

@@ -0,0 +1,55 @@
+import * as z from 'zod';
+
+/**
+ * Schema for LTI Assignment and Grade Services (AGS) Result.
+ * Results contain richer metadata than scores, including user info and timestamps.
+ *
+ * @see https://www.imsglobal.org/spec/lti-ags/v2p0/#result-service
+ */
+export const ResultSchema = z.object({
+  /** Unique identifier for the result */
+  id: z.string(),
+
+  /** Score of the result, represented as a URL */
+  scoreOf: z.url(),
+
+  /** URL identifying the Line Item to which this result belongs. */
+  userId: z.string(),
+
+  /** The score given to the user */
+  resultScore: z.number().optional(),
+
+  /** Maximum possible score */
+  resultMaximum: z.number().optional(),
+
+  /** Comment associated with the result */
+  comment: z.string().optional(),
+
+  /** Timestamp when the result was recorded */
+  timestamp: z.iso.datetime({ offset: true }).optional(),
+
+  /** Activity progress status */
+  activityProgress: z
+    .enum(['Initialized', 'Started', 'InProgress', 'Submitted', 'Completed'])
+    .optional(),
+
+  /** Grading progress status */
+  gradingProgress: z
+    .enum(['FullyGraded', 'Pending', 'PendingManual', 'Failed', 'NotReady'])
+    .optional(),
+});
+
+/**
+ * Schema for an array of results returned from the results service.
+ */
+export const ResultsSchema = z.array(ResultSchema);
+
+/**
+ * Type representing a validated result for LTI AGS.
+ */
+export type Result = z.infer<typeof ResultSchema>;
+
+/**
+ * Type representing an array of results.
+ */
+export type Results = z.infer<typeof ResultsSchema>;

package/src/schemas/lti13/ags/scoreSubmission.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 /**
  * Schema for submitting grades via LTI Assignment and Grade Services (AGS).
@@ -47,6 +47,8 @@ export const ScoreSubmissionSchema = z.object({
     .default('FullyGraded'),
 });
 
+export const ScoreSubmissionsSchema = z.array(ScoreSubmissionSchema);
+
 /**
  * Type representing a validated score submission for LTI AGS.
  * Contains grade data and metadata to be sent to the platform.

package/src/schemas/lti13/claims/baseJwtClaims.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 export const BaseJwtClaimsSchema = z.object({
   iss: z.string(),

package/src/schemas/lti13/claims/contextClaims.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 export const ResourceLinkSchema = z
   .object({

package/src/schemas/lti13/claims/coreLtiClaims.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 export const CoreLtiClaimsSchema = z.object({
   'https://purl.imsglobal.org/spec/lti/claim/message_type': z.union([

package/src/schemas/lti13/claims/platformClaims.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 export const ToolPlatformSchema = z
   .object({

package/src/schemas/lti13/claims/privacyClaims.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 export const PrivacyClaimsSchema = z.object({
   given_name: z.string(),

package/src/schemas/lti13/claims/serviceClaims.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 export const AgsEndpointSchema = z
   .object({

package/src/schemas/lti13/lti13JwtPayload.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 import { BaseJwtClaimsSchema } from './claims/baseJwtClaims.schema.js';
 import { ContextSchema, ResourceLinkSchema } from './claims/contextClaims.schema.js';

package/src/schemas/lti13/lti13Launch.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 export const LTI13LaunchSchema = z.object({
   id_token: z.jwt(),

package/src/schemas/lti13/lti13Login.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 export const LTI13LoginSchema = z.object({
   iss: z.string().min(1),

package/src/schemas/lti13/nrps/contextMembership.schema.ts

@@ -0,0 +1,55 @@
+import * as z from 'zod';
+
+/**
+ * Schema for individual member in NRPS response
+ */
+export const NRPSMemberResponseSchema = z.object({
+  status: z.string(),
+  name: z.string(),
+  picture: z.url().optional(),
+  given_name: z.string().optional(),
+  family_name: z.string().optional(),
+  middle_name: z.string().optional(),
+  email: z.string().optional(), // Platforms don't force email regexp conformance
+  user_id: z.string(),
+  lis_person_sourcedid: z.string().optional(),
+  roles: z.array(z.string()),
+});
+
+/**
+ * Schema for context information in NRPS response
+ */
+export const NRPSContextResponseSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  title: z.string(),
+});
+
+/**
+ * Schema for full NRPS context membership response
+ */
+export const NRPSContextMembershipResponseSchema = z.object({
+  id: z.url(),
+  context: NRPSContextResponseSchema,
+  members: z.array(NRPSMemberResponseSchema),
+});
+
+/**
+ * Clean public API schemas (camelCase for JS/TS consumers)
+ */
+export const MemberSchema = z.object({
+  status: z.string(),
+  name: z.string(),
+  picture: z.url().optional(),
+  givenName: z.string().optional(),
+  familyName: z.string().optional(),
+  middleName: z.string().optional(),
+  email: z.string().optional(), // Platforms don't force email regexp conformance
+  userId: z.string(),
+  lisPersonSourcedId: z.string().optional(),
+  roles: z.array(z.string()),
+});
+
+// Export clean types for public API
+export type Member = z.infer<typeof MemberSchema>;
+export type Context = z.infer<typeof NRPSContextResponseSchema>;

package/src/services/ags.service.ts

@@ -2,6 +2,10 @@ import type { BaseLogger } from 'pino';
 
 import type { LTISession } from '../interfaces/ltiSession.js';
 import type { LTIStorage } from '../interfaces/ltiStorage.js';
+import type {
+  CreateLineItem,
+  UpdateLineItem,
+} from '../schemas/lti13/ags/lineItem.schema.js';
 import type { ScoreSubmission } from '../schemas/lti13/ags/scoreSubmission.schema.js';
 import { getValidLaunchConfig } from '../utils/launchConfigValidation.js';
 
@@ -44,18 +48,8 @@ export class AGSService {
       throw new Error('AGS not available for this session');
     }
 
-    // Get launch config to access token URL
-    const launchConfig = await getValidLaunchConfig(
-      this.storage,
-      session.platform.issuer,
-      session.platform.clientId,
-      session.platform.deploymentId,
-    );
-
-    const token = await this.tokenService.getBearerToken(
-      session.platform.clientId,
-      // Need to get token URL from platform storage
-      launchConfig.tokenUrl,
+    const token = await this.getAGSToken(
+      session,
       'https://purl.imsglobal.org/spec/lti-ags/scope/score',
     );
 
@@ -78,15 +72,258 @@ export class AGSService {
       body: JSON.stringify(scorePayload),
     });
 
+    await this.validateAGSResponse(response, 'score submission');
+    return response;
+  }
+
+  /**
+   * Retrieves all scores for a specific line item from the platform using Assignment and Grade Services.
+   *
+   * @param session - Active LTI session containing AGS line item endpoint configuration
+   * @returns Promise resolving to the HTTP response containing scores data for the line item
+   * @throws {Error} When AGS line item service is not available for the session or request fails
+   *
+   * @example
+   * ```typescript
+   * const response = await agsService.getScores(session);
+   * const scores = await response.json();
+   * console.log('All scores for this line item:', scores);
+   * ```
+   */
+  async getScores(session: LTISession): Promise<Response> {
+    if (!session.services?.ags?.lineitem) {
+      throw new Error('AGS line item not available for this session');
+    }
+
+    const token = await this.getAGSToken(
+      session,
+      'https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly',
+    );
+
+    // cleanse the results URL
+    // we cannot include a search / query param
+    const lineItemUrl = new URL(session.services.ags.lineitem);
+    lineItemUrl.search = '';
+    const resultsUrl = `${lineItemUrl.toString()}/results`;
+
+    const response = await fetch(resultsUrl, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.ims.lis.v2.resultcontainer+json',
+      },
+    });
+
+    await this.validateAGSResponse(response, 'get scores');
+    return response;
+  }
+
+  /**
+   * Retrieves line items (gradebook columns) from the platform using Assignment and Grade Services.
+   *
+   * @param session - Active LTI session containing AGS line items endpoint configuration
+   * @returns Promise resolving to the HTTP response containing line items data
+   * @throws {Error} When AGS line items service is not available for the session or request fails
+   *
+   * @example
+   * ```typescript
+   * const response = await agsService.listLineItems(session);
+   * const lineItems = await response.json();
+   * console.log('Available gradebook columns:', lineItems);
+   * ```
+   */
+  async listLineItems(session: LTISession): Promise<Response> {
+    if (!session.services?.ags?.lineitems) {
+      throw new Error('AGS list line items not available for this session');
+    }
+
+    const token = await this.getAGSToken(
+      session,
+      'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly',
+    );
+
+    const response = await fetch(`${session.services.ags.lineitems}`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.ims.lis.v2.lineitemcontainer+json',
+      },
+    });
+
+    await this.validateAGSResponse(response, 'list line items');
+    return response;
+  }
+
+  /**
+   * Retrieves a specific line item (gradebook column) from the platform using Assignment and Grade Services.
+   *
+   * @param session - Active LTI session containing AGS line item endpoint configuration
+   * @returns Promise resolving to the HTTP response containing the line item data
+   * @throws {Error} When AGS line item service is not available for the session or request fails
+   *
+   * @example
+   * ```typescript
+   * const response = await agsService.getLineItem(session);
+   * const lineItem = await response.json();
+   * console.log('Line item details:', lineItem);
+   * ```
+   */
+  async getLineItem(session: LTISession): Promise<Response> {
+    if (!session.services?.ags?.lineitem) {
+      throw new Error('AGS line item not available for this session');
+    }
+
+    const token = await this.getAGSToken(
+      session,
+      'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly',
+    );
+
+    const response = await fetch(`${session.services.ags.lineitem}`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.ims.lis.v2.lineitem+json',
+      },
+    });
+
+    await this.validateAGSResponse(response, 'get line item');
+    return response;
+  }
+
+  /**
+   * Creates a new line item (gradebook column) on the platform using Assignment and Grade Services.
+   *
+   * @param session - Active LTI session containing AGS line items endpoint configuration
+   * @param createLineItem - Line item data including label, scoreMaximum, and optional metadata
+   * @returns Promise resolving to the HTTP response containing the created line item with generated ID
+   * @throws {Error} When AGS line item creation service is not available for the session or creation fails
+   *
+   * @example
+   * ```typescript
+   * const response = await agsService.createLineItem(session, {
+   *   label: 'Quiz 1',
+   *   scoreMaximum: 100,
+   *   tag: 'quiz',
+   *   resourceId: 'quiz-001'
+   * });
+   * const newLineItem = await response.json();
+   * console.log('Created line item:', newLineItem.id);
+   * ```
+   */
+  async createLineItem(
+    session: LTISession,
+    createLineItem: CreateLineItem,
+  ): Promise<Response> {
+    if (!session.services?.ags?.lineitems) {
+      throw new Error('AGS create line items not available for this session');
+    }
+
+    const token = await this.getAGSToken(
+      session,
+      'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem',
+    );
+
+    const response = await fetch(`${session.services.ags.lineitems}`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/vnd.ims.lis.v2.lineitem+json',
+      },
+      body: JSON.stringify(createLineItem),
+    });
+
+    await this.validateAGSResponse(response, 'create line item');
+    return response;
+  }
+
+  /**
+   * Updates an existing line item (gradebook column) on the platform using Assignment and Grade Services.
+   *
+   * @param session - Active LTI session containing AGS line item endpoint configuration
+   * @param updateLineItem - Updated line item data including all required fields
+   * @returns Promise resolving to the HTTP response containing the updated line item
+   * @throws {Error} When AGS line item service is not available for the session or update fails
+   */
+  async updateLineItem(
+    session: LTISession,
+    updateLineItem: UpdateLineItem,
+  ): Promise<Response> {
+    if (!session.services?.ags?.lineitem) {
+      throw new Error('AGS line item not available for this session');
+    }
+
+    const token = await this.getAGSToken(
+      session,
+      'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem',
+    );
+
+    const response = await fetch(session.services.ags.lineitem, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/vnd.ims.lis.v2.lineitem+json',
+      },
+      body: JSON.stringify(updateLineItem),
+    });
+
+    await this.validateAGSResponse(response, 'update line item');
+    return response;
+  }
+
+  /**
+   * Deletes a line item (gradebook column) from the platform using Assignment and Grade Services.
+   *
+   * @param session - Active LTI session containing AGS line item endpoint configuration
+   * @returns Promise resolving to the HTTP response (typically 204 No Content on success)
+   * @throws {Error} When AGS line item service is not available for the session or deletion fails
+   */
+  async deleteLineItem(session: LTISession): Promise<Response> {
+    if (!session.services?.ags?.lineitem) {
+      throw new Error('AGS line item not available for this session');
+    }
+
+    const token = await this.getAGSToken(
+      session,
+      'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem',
+    );
+
+    const response = await fetch(session.services.ags.lineitem, {
+      method: 'DELETE',
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    });
+
+    await this.validateAGSResponse(response, 'delete line item');
+    return response;
+  }
+
+  private async getAGSToken(session: LTISession, scope: string): Promise<string> {
+    const launchConfig = await getValidLaunchConfig(
+      this.storage,
+      session.platform.issuer,
+      session.platform.clientId,
+      session.platform.deploymentId,
+    );
+
+    return this.tokenService.getBearerToken(
+      session.platform.clientId,
+      launchConfig.tokenUrl,
+      scope,
+    );
+  }
+
+  private async validateAGSResponse(
+    response: Response,
+    operation: string,
+  ): Promise<void> {
     if (!response.ok) {
       const error = await response.json();
       this.logger.error(
         { error, status: response.status, statusText: response.statusText },
-        'AGS score submission failed',
+        `AGS ${operation} failed`,
       );
-      throw new Error(`AGS score submission failed: ${response.statusText}`);
+      throw new Error(`AGS ${operation} failed: ${response.statusText} ${error}`);
     }
-
-    return response;
   }
 }

package/src/services/nrps.service.ts

@@ -0,0 +1,80 @@
+import type { BaseLogger } from 'pino';
+
+import type { LTISession } from '../interfaces/ltiSession.js';
+import type { LTIStorage } from '../interfaces/ltiStorage.js';
+import { getValidLaunchConfig } from '../utils/launchConfigValidation.js';
+
+import type { TokenService } from './token.service.js';
+
+/**
+ * Names and Role Provisioning Services (NRPS) implementation for LTI 1.3.
+ * Provides methods to retrieve course membership and user information from the platform.
+ *
+ * @see https://www.imsglobal.org/spec/lti-nrps/v2p0
+ */
+export class NRPSService {
+  constructor(
+    private tokenService: TokenService,
+    private storage: LTIStorage,
+    private logger: BaseLogger,
+  ) {}
+
+  /**
+   * Retrieves all members (users) in the current course/context from the platform.
+   * Returns raw response that should be parsed by the calling service.
+   *
+   * @param session - Active LTI session containing NRPS service endpoints
+   * @returns Raw HTTP response containing membership data
+   * @throws {Error} When NRPS is not available for this session or request fails
+   */
+  async getMembers(session: LTISession): Promise<Response> {
+    if (!session.services?.nrps?.membershipUrl) {
+      throw new Error('NRPS not available for this session');
+    }
+
+    const token = await this.getNRPSToken(
+      session,
+      'https://purl.imsglobal.org/spec/lti-nrps/scope/contextmembership.readonly',
+    );
+
+    const response = await fetch(session.services.nrps.membershipUrl, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.ims.lti-nrps.v2.membershipcontainer+json',
+      },
+    });
+
+    await this.validateNRPSResponse(response, 'get members');
+    return response;
+  }
+
+  private async getNRPSToken(session: LTISession, scope: string): Promise<string> {
+    const launchConfig = await getValidLaunchConfig(
+      this.storage,
+      session.platform.issuer,
+      session.platform.clientId,
+      session.platform.deploymentId,
+    );
+
+    return this.tokenService.getBearerToken(
+      session.platform.clientId,
+      launchConfig.tokenUrl,
+      scope,
+    );
+  }
+
+  private async validateNRPSResponse(
+    response: Response,
+    operation: string,
+  ): Promise<void> {
+    if (!response.ok) {
+      const error = await response.json();
+      this.logger.error(
+        { error, status: response.status, statusText: response.statusText },
+        `NRPS ${operation} failed`,
+      );
+      throw new Error(`NRPS ${operation} failed: ${response.statusText} ${error}`);
+    }
+  }
+}

package/src/services/token.service.ts

@@ -70,7 +70,10 @@ export class TokenService {
     });
 
     if (!response.ok) {
-      throw new Error(`Token request failed: ${response.status} ${response.statusText}`);
+      const errorDetail = await response.json();
+      throw new Error(
+        `Token request failed: ${response.status} ${response.statusText} ${errorDetail}`,
+      );
     }
 
     const tokenData = await response.json();