@lti-tool/core 0.9.0 → 0.11.0

package/dist/services/ags.service.js

@@ -37,11 +37,7 @@ export class AGSService {
         if (!session.services?.ags?.lineitem) {
             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, 'https://purl.imsglobal.org/spec/lti-ags/scope/score');
+        const token = await this.getAGSToken(session, 'https://purl.imsglobal.org/spec/lti-ags/scope/score');
         const scorePayload = {
             userId: score.userId,
             scoreGiven: score.scoreGiven,
@@ -59,11 +55,191 @@ 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) {
+        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) {
+        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) {
+        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, createLineItem) {
+        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, updateLineItem) {
+        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) {
+        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;
+    }
+    async getAGSToken(session, scope) {
+        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);
+    }
+    async validateAGSResponse(response, operation) {
         if (!response.ok) {
             const error = await response.json();
-            this.logger.error({ error, status: response.status, statusText: response.statusText }, 'AGS score submission failed');
-            throw new Error(`AGS score submission failed: ${response.statusText}`);
+            this.logger.error({ error, status: response.status, statusText: response.statusText }, `AGS ${operation} failed`);
+            throw new Error(`AGS ${operation} failed: ${response.statusText} ${error}`);
         }
-        return response;
     }
 }

package/dist/services/nrps.service.d.ts

@@ -0,0 +1,28 @@
+import type { BaseLogger } from 'pino';
+import type { LTISession } from '../interfaces/ltiSession.js';
+import type { LTIStorage } from '../interfaces/ltiStorage.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 declare class NRPSService {
+    private tokenService;
+    private storage;
+    private logger;
+    constructor(tokenService: TokenService, storage: LTIStorage, 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
+     */
+    getMembers(session: LTISession): Promise<Response>;
+    private getNRPSToken;
+    private validateNRPSResponse;
+}
+//# sourceMappingURL=nrps.service.d.ts.map

package/dist/services/nrps.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nrps.service.d.ts","sourceRoot":"","sources":["../../src/services/nrps.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;gBAFN,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,UAAU;IAG5B;;;;;;;OAOG;IACG,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;YAsB1C,YAAY;YAeZ,oBAAoB;CAanC"}

package/dist/services/nrps.service.js

@@ -0,0 +1,51 @@
+import { getValidLaunchConfig } from '../utils/launchConfigValidation.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 {
+    tokenService;
+    storage;
+    logger;
+    constructor(tokenService, storage, logger) {
+        this.tokenService = tokenService;
+        this.storage = storage;
+        this.logger = logger;
+    }
+    /**
+     * 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) {
+        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;
+    }
+    async getNRPSToken(session, scope) {
+        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);
+    }
+    async validateNRPSResponse(response, operation) {
+        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/dist/services/token.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token.service.d.ts","sourceRoot":"","sources":["../../src/services/token.service.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,qBAAa,YAAY;IAQrB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,KAAK;IARf;;;;;OAKG;gBAEO,OAAO,EAAE,aAAa,EACtB,KAAK,SAAS;IAGxB;;;;;;OAMG;IACG,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBhF;;;;;;;OAOG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC;CA0BnB"}
+{"version":3,"file":"token.service.d.ts","sourceRoot":"","sources":["../../src/services/token.service.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,qBAAa,YAAY;IAQrB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,KAAK;IARf;;;;;OAKG;gBAEO,OAAO,EAAE,aAAa,EACtB,KAAK,SAAS;IAGxB;;;;;;OAMG;IACG,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBhF;;;;;;;OAOG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC;CA6BnB"}

package/dist/services/token.service.js

@@ -63,7 +63,8 @@ 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();
         if (!tokenData.access_token) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lti-tool/core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "LTI 1.3 implementation for Node.js",
   "keywords": [
     "lti",

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,8 +14,22 @@ 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 {
+  type Member,
+  NRPSContextMembershipResponseSchema,
+} from './schemas/lti13/nrps/contextMembership.schema.js';
 import { AGSService } from './services/ags.service.js';
+import { NRPSService } from './services/nrps.service.js';
 import { createSession } from './services/session.service.js';
 import { TokenService } from './services/token.service.js';
 import { getValidLaunchConfig } from './utils/launchConfigValidation.js';
@@ -49,6 +63,7 @@ export class LTITool {
   private logger: Logger;
   private tokenService: TokenService;
   private agsService: AGSService;
+  private nrpsService: NRPSService;
 
   /**
    * Creates a new LTI Tool instance.
@@ -70,6 +85,11 @@ export class LTITool {
       this.config.security?.keyId ?? 'main',
     );
     this.agsService = new AGSService(this.tokenService, this.config.storage, this.logger);
+    this.nrpsService = new NRPSService(
+      this.tokenService,
+      this.config.storage,
+      this.logger,
+    );
   }
 
   /**
@@ -259,17 +279,187 @@ 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);
+  }
+
+  /**
+   * Retrieves course/context members using Names and Role Provisioning Services (NRPS).
+   *
+   * @param session - Active LTI session containing NRPS service endpoints
+   * @returns Array of members with clean camelCase properties
+   * @throws {Error} When NRPS is not available or request fails
+   *
+   * @example
+   * ```typescript
+   * const members = await ltiTool.getMembers(session);
+   * const instructors = members.filter(m =>
+   *   m.roles.some(role => role.includes('Instructor'))
+   * );
+   * ```
+   */
+  async getMembers(session: LTISession): Promise<Member[]> {
+    if (!session) {
+      throw new Error('session is required');
+    }
+
+    const response = await this.nrpsService.getMembers(session);
+    const data = await response.json();
+    console.log(data);
+    const validated = NRPSContextMembershipResponseSchema.parse(data);
+
+    // Transform to clean camelCase format
+    return validated.members.map((member) => ({
+      status: member.status,
+      name: member.name,
+      picture: member.picture,
+      givenName: member.given_name,
+      familyName: member.family_name,
+      middleName: member.middle_name,
+      email: member.email,
+      userId: member.user_id,
+      lisPersonSourcedId: member.lis_person_sourcedid,
+      roles: member.roles,
+    }));
   }
 
   // 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>;