@lti-tool/core 0.9.0 → 0.10.0

package/src/ltiTool.ts

@@ -1,4 +1,4 @@
-import { SignJWT, createRemoteJWKSet, decodeJwt, exportJWK, jwtVerify } from 'jose';
+import { createRemoteJWKSet, decodeJwt, exportJWK, jwtVerify, SignJWT } from 'jose';
 import type { Logger } from 'pino';
 
 import type { JWKS } from './interfaces/jwks.js';
@@ -14,7 +14,16 @@ import {
   SessionIdSchema,
   VerifyLaunchParamsSchema,
 } from './schemas/index.js';
-import type { ScoreSubmission } from './schemas/lti13/ags/scoreSubmission.schema.js';
+import {
+  type CreateLineItem,
+  type LineItem,
+  type LineItems,
+  LineItemSchema,
+  LineItemsSchema,
+  type UpdateLineItem,
+} from './schemas/lti13/ags/lineItem.schema.js';
+import { type Results, ResultsSchema } from './schemas/lti13/ags/result.schema.js';
+import { type ScoreSubmission } from './schemas/lti13/ags/scoreSubmission.schema.js';
 import { AGSService } from './services/ags.service.js';
 import { createSession } from './services/session.service.js';
 import { TokenService } from './services/token.service.js';
@@ -259,17 +268,147 @@ export class LTITool {
    *
    * @param session - Active LTI session containing AGS service endpoints
    * @param score - Score submission data including grade value and user ID
-   * @returns Result of the score submission
    * @throws {Error} When AGS is not available or submission fails
    */
-  async submitScore(session: LTISession, score: ScoreSubmission): Promise<Response> {
+  async submitScore(session: LTISession, score: ScoreSubmission): Promise<void> {
     if (!session) {
       throw new Error('session is required');
     }
     if (!score) {
       throw new Error('score is required');
     }
-    return await this.agsService.submitScore(session, score);
+
+    await this.agsService.submitScore(session, score);
+  }
+
+  /**
+   * Retrieves all scores for a specific line item from the platform using Assignment and Grade Services (AGS).
+   *
+   * @param session - Active LTI session containing AGS service endpoints
+   * @returns Array of score submissions for the line item
+   * @throws {Error} When AGS is not available or request fails
+   *
+   * @example
+   * ```typescript
+   * const scores = await ltiTool.getScores(session);
+   * console.log('All scores:', scores.map(s => `${s.userId}: ${s.scoreGiven}`));
+   * ```
+   */
+  async getScores(session: LTISession): Promise<Results> {
+    if (!session) {
+      throw new Error('session is required');
+    }
+
+    const response = await this.agsService.getScores(session);
+    const data = await response.json();
+    return ResultsSchema.parse(data);
+  }
+
+  /**
+   * Retrieves line items (gradebook columns) from the platform using Assignment and Grade Services (AGS).
+   *
+   * @param session - Active LTI session containing AGS service endpoints
+   * @returns Array of line items from the platform
+   * @throws {Error} When AGS is not available or request fails
+   */
+  async listLineItems(session: LTISession): Promise<LineItems> {
+    if (!session) {
+      throw new Error('session is required');
+    }
+
+    const response = await this.agsService.listLineItems(session);
+    const data = await response.json();
+    return LineItemsSchema.parse(data);
+  }
+
+  /**
+   * Retrieves a specific line item (gradebook column) from the platform using Assignment and Grade Services (AGS).
+   *
+   * @param session - Active LTI session containing AGS service endpoints
+   * @returns Line item data from the platform
+   * @throws {Error} When AGS is not available or request fails
+   */
+  async getLineItem(session: LTISession): Promise<LineItem> {
+    if (!session) {
+      throw new Error('session is required');
+    }
+
+    const response = await this.agsService.getLineItem(session);
+    const data = await response.json();
+    return LineItemSchema.parse(data);
+  }
+
+  /**
+   * Creates a new line item (gradebook column) on the platform using Assignment and Grade Services (AGS).
+   *
+   * @param session - Active LTI session containing AGS service endpoints
+   * @param createLineItem - Line item data including label, scoreMaximum, and optional metadata
+   * @returns Created line item with platform-generated ID and validated data
+   * @throws {Error} When AGS is not available, input validation fails, or creation fails
+   *
+   * @example
+   * ```typescript
+   * const newLineItem = await ltiTool.createLineItem(session, {
+   *   label: 'Quiz 1',
+   *   scoreMaximum: 100,
+   *   tag: 'quiz',
+   *   resourceId: 'quiz-001'
+   * });
+   * console.log('Created line item:', newLineItem.id);
+   * ```
+   */
+  async createLineItem(
+    session: LTISession,
+    createLineItem: CreateLineItem,
+  ): Promise<LineItem> {
+    if (!session) {
+      throw new Error('session is required');
+    }
+    if (!createLineItem) {
+      throw new Error('createLineItem is required');
+    }
+
+    const response = await this.agsService.createLineItem(session, createLineItem);
+    const data = await response.json();
+    return LineItemSchema.parse(data);
+  }
+
+  /**
+   * Updates an existing line item (gradebook column) on the platform using Assignment and Grade Services (AGS).
+   *
+   * @param session - Active LTI session containing AGS service endpoints
+   * @param updateLineItem - Updated line item data including all required fields
+   * @returns Updated line item with validated data from the platform
+   * @throws {Error} When AGS is not available, input validation fails, or update fails
+   */
+  async updateLineItem(
+    session: LTISession,
+    updateLineItem: UpdateLineItem,
+  ): Promise<LineItem> {
+    if (!session) {
+      throw new Error('session is required');
+    }
+    if (!updateLineItem) {
+      throw new Error('lineItem is required');
+    }
+
+    const response = await this.agsService.updateLineItem(session, updateLineItem);
+    const data = await response.json();
+    return LineItemSchema.parse(data);
+  }
+
+  /**
+   * Deletes a line item (gradebook column) from the platform using Assignment and Grade Services (AGS).
+   *
+   * @param session - Active LTI session containing AGS service endpoints
+   * @throws {Error} When AGS is not available or deletion fails
+   */
+  async deleteLineItem(session: LTISession): Promise<void> {
+    if (!session) {
+      throw new Error('session is required');
+    }
+
+    await this.agsService.deleteLineItem(session);
   }
 
   // Client management

package/src/schemas/client.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 import { DeploymentSchema } from './deployment.schema';
 

package/src/schemas/common.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 /**
  * Common validation schemas used across the LTI tool

package/src/schemas/deployment.schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 export const DeploymentSchema = z.object({
   id: z.uuid().describe('Internal stable UUID for this deployment configuration'),

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

@@ -0,0 +1,85 @@
+import * as z from 'zod';
+
+/**
+ * Schema for LTI Assignment and Grade Services (AGS) Line Item.
+ * Represents a gradebook column/assignment according to LTI AGS v2.0 specification.
+ *
+ * @see https://www.imsglobal.org/spec/lti-ags/v2p0/#line-item-service
+ */
+export const LineItemSchema = z.object({
+  /** Unique identifier for the line item */
+  id: z.url(),
+
+  /** Maximum score possible for this line item */
+  scoreMaximum: z.number().min(0),
+
+  /** Human-readable label for the line item */
+  label: z.string(),
+
+  /** Optional resource identifier that this line item is associated with */
+  resourceId: z.string().optional(),
+
+  /** Optional resource link identifier */
+  resourceLinkId: z.string().optional(),
+
+  /** Optional tag to identify the line item */
+  tag: z.string().optional(),
+
+  /** Optional start date/time for the assignment */
+  startDateTime: z.iso.datetime().optional(),
+
+  /** Optional end date/time for the assignment */
+  endDateTime: z.iso.datetime().optional(),
+});
+
+/**
+ * Schema for creating a new LTI Assignment and Grade Services (AGS) Line Item.
+ * Omits the 'id' field since it's generated by the platform upon creation.
+ *
+ * @see https://www.imsglobal.org/spec/lti-ags/v2p0/#line-item-service
+ */
+export const CreateLineItemSchema = LineItemSchema.omit({
+  id: true,
+});
+
+/**
+ * Schema for updating an existing LTI Assignment and Grade Services (AGS) Line Item.
+ * Omits 'id' and 'resourceLinkId' fields as they are immutable per LTI AGS specification.
+ * Tools MUST NOT change these values during updates.
+ *
+ * @see https://www.imsglobal.org/spec/lti-ags/v2p0/#line-item-service
+ */
+export const UpdateLineItemSchema = LineItemSchema.omit({
+  id: true,
+  resourceLinkId: true,
+});
+
+/**
+ * Schema for an array of line items returned from the line items service.
+ */
+export const LineItemsSchema = z.array(LineItemSchema);
+
+// types
+
+/**
+ * Type representing a validated line item for LTI AGS.
+ * Represents a gradebook column or assignment.
+ */
+export type LineItem = z.infer<typeof LineItemSchema>;
+
+/**
+ * Type representing an array of line items.
+ */
+export type LineItems = z.infer<typeof LineItemsSchema>;
+
+/**
+ * Type representing data required to create a new line item for LTI AGS.
+ * Contains all LineItem fields except the platform-generated 'id'.
+ */
+export type CreateLineItem = z.infer<typeof CreateLineItemSchema>;
+
+/**
+ * Type representing data for updating an existing line item for LTI AGS.
+ * Contains all LineItem fields except immutable 'id' and 'resourceLinkId'.
+ */
+export type UpdateLineItem = z.infer<typeof UpdateLineItemSchema>;

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),