@lti-tool/core 0.13.0 → 0.13.2

package/src/services/ags.service.ts

@@ -18,6 +18,13 @@ import type { TokenService } from './token.service.js';
  * @see https://www.imsglobal.org/spec/lti-ags/v2p0
  */
 export class AGSService {
+  /**
+   * Creates a new AGSService instance.
+   *
+   * @param tokenService - Token service for obtaining OAuth2 bearer tokens
+   * @param storage - Storage adapter for retrieving launch configurations
+   * @param logger - Logger instance for debug and error logging
+   */
   constructor(
     private tokenService: TokenService,
     private storage: LTIStorage,
@@ -243,6 +250,16 @@ export class AGSService {
    * @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
+   *
+   * @example
+   * ```typescript
+   * const response = await agsService.updateLineItem(session, {
+   *   label: 'Quiz 1 (Updated)',
+   *   scoreMaximum: 100,
+   *   tag: 'quiz'
+   * });
+   * const updatedLineItem = await response.json();
+   * ```
    */
   async updateLineItem(
     session: LTISession,
@@ -276,6 +293,12 @@ export class AGSService {
    * @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
+   *
+   * @example
+   * ```typescript
+   * const response = await agsService.deleteLineItem(session);
+   * console.log('Line item deleted successfully');
+   * ```
    */
   async deleteLineItem(session: LTISession): Promise<Response> {
     if (!session.services?.ags?.lineitem) {

package/src/services/deepLinking.service.ts

@@ -8,11 +8,16 @@ import type { DeepLinkingContentItem } from '../schemas/lti13/deepLinking/conten
  * Deep Linking service for LTI 1.3.
  * Generates signed JWT responses containing selected content items to return to the platform.
  *
- * @param keyPair - RSA key pair for signing client assertion JWTs (must be RS256 compatible)
- * @param keyId - Key identifier for JWT header, should match JWKS key ID (defaults to 'main')
  * @see https://www.imsglobal.org/spec/lti-dl/v2p0
  */
 export class DeepLinkingService {
+  /**
+   * Creates a new DeepLinkingService instance.
+   *
+   * @param keyPair - RSA key pair for signing client assertion JWTs (must be RS256 compatible)
+   * @param logger - Logger instance for debug and error logging
+   * @param keyId - Key identifier for JWT header, should match JWKS key ID (defaults to 'main')
+   */
   constructor(
     private keyPair: CryptoKeyPair,
     private logger: BaseLogger,
@@ -25,7 +30,7 @@ export class DeepLinkingService {
    *
    * @param session - Active LTI session containing Deep Linking configuration
    * @param contentItems - Array of content items selected by the user
-   * @returns HTML string containing auto-submit form
+   * @returns Promise resolving to an HTML string containing auto-submit form
    * @throws {Error} When Deep Linking is not available for the session
    *
    * @example
@@ -65,7 +70,7 @@ export class DeepLinkingService {
    *
    * @param session - Active LTI session with Deep Linking configuration
    * @param contentItems - Array of selected content items
-   * @returns Signed JWT string
+   * @returns Promise resolving to a signed JWT string
    */
   private async createDeepLinkingJWT(
     session: LTISession,

package/src/services/dynamicRegistration.service.ts

@@ -63,6 +63,13 @@ import {
  * @see https://www.imsglobal.org/spec/lti-dr/v1p0 LTI 1.3 Dynamic Registration specification
  */
 export class DynamicRegistrationService {
+  /**
+   * Creates a new DynamicRegistrationService instance.
+   *
+   * @param storage - Storage adapter for persisting client and deployment configurations
+   * @param dynamicRegistrationConfig - Tool configuration including URLs and service settings
+   * @param logger - Logger instance for debug and error logging
+   */
   constructor(
     private storage: LTIStorage,
     private dynamicRegistrationConfig: DynamicRegistrationConfig,

package/src/services/nrps.service.ts

@@ -13,6 +13,13 @@ import type { TokenService } from './token.service.js';
  * @see https://www.imsglobal.org/spec/lti-nrps/v2p0
  */
 export class NRPSService {
+  /**
+   * Creates a new NRPSService instance.
+   *
+   * @param tokenService - Token service for obtaining OAuth2 bearer tokens
+   * @param storage - Storage adapter for retrieving launch configurations
+   * @param logger - Logger instance for debug and error logging
+   */
   constructor(
     private tokenService: TokenService,
     private storage: LTIStorage,
@@ -24,8 +31,15 @@ export class NRPSService {
    * 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
+   * @returns Promise resolving to the HTTP response containing membership data
    * @throws {Error} When NRPS is not available for this session or request fails
+   *
+   * @example
+   * ```typescript
+   * const response = await nrpsService.getMembers(session);
+   * const data = await response.json();
+   * console.log('Course members:', data.members);
+   * ```
    */
   async getMembers(session: LTISession): Promise<Response> {
     if (!session.services?.nrps?.membershipUrl) {

package/src/services/token.service.ts

@@ -6,6 +6,8 @@ import { SignJWT } from 'jose';
  *
  * Implements RFC 7523 (JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants)
  * as required by LTI 1.3 security framework.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc7523
  */
 export class TokenService {
   /**
@@ -24,7 +26,7 @@ export class TokenService {
    *
    * @param clientId - OAuth2 client identifier
    * @param tokenUrl - Platform's token endpoint URL
-   * @returns Signed JWT client assertion
+   * @returns Promise resolving to a signed JWT client assertion string
    */
   async createClientAssertion(clientId: string, tokenUrl: string): Promise<string> {
     return await new SignJWT({
@@ -49,7 +51,8 @@ export class TokenService {
    * @param clientId - OAuth2 client identifier
    * @param tokenUrl - Platform's token endpoint URL
    * @param scope - Requested OAuth2 scope (e.g., AGS score scope)
-   * @returns Bearer access token for API calls
+   * @returns Promise resolving to a bearer access token string for API calls
+   * @throws {Error} When the token request fails or response is missing access_token
    */
   async getBearerToken(
     clientId: string,

package/src/utils/errorFormatting.ts

@@ -0,0 +1,22 @@
+/**
+ * Formats an unknown error into a readable string message.
+ * Handles Error objects, strings, and other types safely.
+ *
+ * @param error - The error to format (can be Error, string, or any other type)
+ * @returns Formatted error message string
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   throw new Error(`Operation failed: ${formatError(error)}`);
+ * }
+ * ```
+ */
+export function formatError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}