@lti-tool/core 0.12.2 → 0.13.1

package/package.json

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

package/src/ltiTool.ts

@@ -27,12 +27,14 @@ import {
 } 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 DeepLinkingContentItem } from './schemas/lti13/deepLinking/contentItem.schema.js';
 import { type OpenIDConfiguration } from './schemas/lti13/dynamicRegistration/openIDConfiguration.schema.js';
 import {
   type Member,
   NRPSContextMembershipResponseSchema,
 } from './schemas/lti13/nrps/contextMembership.schema.js';
 import { AGSService } from './services/ags.service.js';
+import { DeepLinkingService } from './services/deepLinking.service.js';
 import { DynamicRegistrationService } from './services/dynamicRegistration.service.js';
 import { NRPSService } from './services/nrps.service.js';
 import { createSession } from './services/session.service.js';
@@ -69,6 +71,7 @@ export class LTITool {
   private tokenService: TokenService;
   private agsService: AGSService;
   private nrpsService: NRPSService;
+  private deepLinkingService: DeepLinkingService;
   private dynamicRegistrationService?: DynamicRegistrationService;
 
   /**
@@ -96,6 +99,11 @@ export class LTITool {
       this.config.storage,
       this.logger,
     );
+    this.deepLinkingService = new DeepLinkingService(
+      this.config.keyPair,
+      this.logger,
+      this.config.security?.keyId ?? 'main',
+    );
     if (this.config.dynamicRegistration) {
       this.dynamicRegistrationService = new DynamicRegistrationService(
         this.config.storage,
@@ -474,6 +482,41 @@ export class LTITool {
     }));
   }
 
+  /**
+   * Creates a Deep Linking response with selected content items.
+   * Generates a signed JWT and returns HTML form that auto-submits to the platform.
+   *
+   * @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
+   * @throws {Error} When Deep Linking is not available for the session
+   *
+   * @example
+   * ```typescript
+   * const html = await ltiTool.createDeepLinkingResponse(session, [
+   *   {
+   *     type: 'ltiResourceLink',
+   *     title: 'Quiz 1',
+   *     url: 'https://tool.example.com/quiz/1'
+   *   }
+   * ]);
+   * // Render the HTML to return content items to platform
+   * ```
+   */
+  async createDeepLinkingResponse(
+    session: LTISession,
+    contentItems: DeepLinkingContentItem[],
+  ): Promise<string> {
+    if (!session) {
+      throw new Error('session is required');
+    }
+    if (!contentItems) {
+      throw new Error('contentItems is required');
+    }
+
+    return await this.deepLinkingService.createResponse(session, contentItems);
+  }
+
   /**
    * Fetches and validates the OpenID Connect configuration from an LTI platform during dynamic registration.
    * Validates that the OIDC endpoint and issuer have matching hostnames for security.
@@ -536,7 +579,7 @@ export class LTITool {
     dynamicRegistrationForm: DynamicRegistrationForm,
   ): Promise<string> {
     if (!this.dynamicRegistrationService) {
-      throw new Error('Dynmaic registration service is not configured');
+      throw new Error('Dynamic registration service is not configured');
     }
 
     return await this.dynamicRegistrationService.completeDynamicRegistration(

package/src/schemas/index.ts

@@ -1,4 +1,13 @@
 export { SessionIdSchema } from './common.schema.js';
+export {
+  ContentItemSchema,
+  type DeepLinkingContentItem,
+  type DeepLinkingFile,
+  type DeepLinkingHtml,
+  type DeepLinkingImage,
+  type DeepLinkingLink,
+  type DeepLinkingLtiResourceLink,
+} from './lti13/deepLinking/contentItem.schema.js';
 export {
   DynamicRegistrationFormSchema,
   type DynamicRegistrationForm,

package/src/schemas/lti13/deepLinking/contentItem.schema.ts

@@ -0,0 +1,206 @@
+import * as z from 'zod';
+
+/**
+ * Zod schema for base content item properties shared across all content item types.
+ * Contains common metadata fields like title, text, icon, and thumbnail.
+ *
+ * @property title - Optional human-readable title for the content item
+ * @property text - Optional descriptive text for the content item
+ * @property icon - Optional icon image with URL and dimensions
+ * @property thumbnail - Optional thumbnail image with URL and dimensions
+ *
+ * @see https://www.imsglobal.org/spec/lti-dl/v2p0#content-item-types
+ */
+const BaseContentItemSchema = z.object({
+  title: z.string().optional(),
+  text: z.string().optional(),
+  icon: z
+    .object({
+      url: z.url(),
+      width: z.number().optional(),
+      height: z.number().optional(),
+    })
+    .optional(),
+  thumbnail: z
+    .object({
+      url: z.url(),
+      width: z.number().optional(),
+      height: z.number().optional(),
+    })
+    .optional(),
+});
+
+/**
+ * Zod schema for LTI Resource Link content item.
+ * Represents a launchable LTI tool resource that can be embedded in the platform.
+ *
+ * @property type - Always 'ltiResourceLink' for this content type
+ * @property url - Optional launch URL for the resource
+ * @property custom - Optional custom parameters passed to the tool on launch
+ * @property lineItem - Optional gradebook column configuration for this resource
+ * @property available - Optional availability window with start/end dates
+ * @property submission - Optional submission window with start/end dates
+ *
+ * @see https://www.imsglobal.org/spec/lti-dl/v2p0#lti-resource-link
+ */
+export const LtiResourceLinkSchema = BaseContentItemSchema.extend({
+  type: z.literal('ltiResourceLink'),
+  url: z.url().optional(),
+  custom: z.record(z.string(), z.string()).optional(),
+  lineItem: z
+    .object({
+      scoreMaximum: z.number().min(0),
+      label: z.string(),
+      resourceId: z.string().optional(),
+      tag: z.string().optional(),
+    })
+    .optional(),
+  available: z
+    .object({
+      startDateTime: z.iso.datetime().optional(),
+      endDateTime: z.iso.datetime().optional(),
+    })
+    .optional(),
+  submission: z
+    .object({
+      startDateTime: z.iso.datetime().optional(),
+      endDateTime: z.iso.datetime().optional(),
+    })
+    .optional(),
+});
+
+/**
+ * Zod schema for simple link content item.
+ * Represents a standard web link that can be opened in various ways.
+ *
+ * @property type - Always 'link' for this content type
+ * @property url - Target URL for the link
+ * @property embed - Optional HTML embed code
+ * @property window - Optional window configuration for opening the link
+ * @property iframe - Optional iframe configuration for embedding the link
+ *
+ * @see https://www.imsglobal.org/spec/lti-dl/v2p0#link
+ */
+export const LinkSchema = BaseContentItemSchema.extend({
+  type: z.literal('link'),
+  url: z.url(),
+  embed: z
+    .object({
+      html: z.string(),
+    })
+    .optional(),
+  window: z
+    .object({
+      targetName: z.string().optional(),
+      windowFeatures: z.string().optional(),
+    })
+    .optional(),
+  iframe: z
+    .object({
+      width: z.number().optional(),
+      height: z.number().optional(),
+      src: z.url(),
+    })
+    .optional(),
+});
+
+/**
+ * Zod schema for HTML fragment content item.
+ * Represents raw HTML content to be embedded directly in the platform.
+ *
+ * @property type - Always 'html' for this content type
+ * @property html - HTML content to be embedded
+ *
+ * @see https://www.imsglobal.org/spec/lti-dl/v2p0#html-fragment
+ */
+export const HtmlSchema = BaseContentItemSchema.extend({
+  type: z.literal('html'),
+  html: z.string(),
+});
+
+/**
+ * Zod schema for file content item.
+ * Represents a downloadable file resource.
+ *
+ * @property type - Always 'file' for this content type
+ * @property url - URL to download the file
+ * @property mediaType - MIME type of the file
+ * @property expiresAt - Optional expiration timestamp for the file URL
+ *
+ * @see https://www.imsglobal.org/spec/lti-dl/v2p0#file
+ */
+export const FileSchema = BaseContentItemSchema.extend({
+  type: z.literal('file'),
+  url: z.url(),
+  mediaType: z.string(),
+  expiresAt: z.iso.datetime().optional(),
+});
+
+/**
+ * Zod schema for image content item.
+ * Represents an image resource with optional dimensions.
+ *
+ * @property type - Always 'image' for this content type
+ * @property url - URL to the image
+ * @property width - Optional image width in pixels
+ * @property height - Optional image height in pixels
+ *
+ * @see https://www.imsglobal.org/spec/lti-dl/v2p0#image
+ */
+export const ImageSchema = BaseContentItemSchema.extend({
+  type: z.literal('image'),
+  url: z.url(),
+  width: z.number().optional(),
+  height: z.number().optional(),
+});
+
+/**
+ * Zod schema for validating any Deep Linking content item type.
+ * Uses discriminated union on the 'type' field to determine the specific content item schema.
+ * Supports: ltiResourceLink, link, html, file, and image content types.
+ *
+ * @see https://www.imsglobal.org/spec/lti-dl/v2p0#content-item-types
+ */
+export const ContentItemSchema = z.discriminatedUnion('type', [
+  LtiResourceLinkSchema,
+  LinkSchema,
+  HtmlSchema,
+  FileSchema,
+  ImageSchema,
+]);
+
+/**
+ * Type representing a validated LTI Resource Link content item.
+ * Used for creating launchable LTI tool resources.
+ */
+export type DeepLinkingLtiResourceLink = z.infer<typeof LtiResourceLinkSchema>;
+
+/**
+ * Type representing a validated simple link content item.
+ * Used for creating standard web links.
+ */
+export type DeepLinkingLink = z.infer<typeof LinkSchema>;
+
+/**
+ * Type representing a validated HTML fragment content item.
+ * Used for embedding raw HTML content.
+ */
+export type DeepLinkingHtml = z.infer<typeof HtmlSchema>;
+
+/**
+ * Type representing a validated file content item.
+ * Used for linking to downloadable files.
+ */
+export type DeepLinkingFile = z.infer<typeof FileSchema>;
+
+/**
+ * Type representing a validated image content item.
+ * Used for embedding images.
+ */
+export type DeepLinkingImage = z.infer<typeof ImageSchema>;
+
+/**
+ * Type representing any validated Deep Linking content item.
+ * Can be any of: DeepLinkingLtiResourceLink, DeepLinkingLink, DeepLinkingHtml, DeepLinkingFile, or DeepLinkingImage.
+ */
+export type DeepLinkingContentItem = z.infer<typeof ContentItemSchema>;

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

@@ -0,0 +1,128 @@
+import { SignJWT } from 'jose';
+import type { BaseLogger } from 'pino';
+
+import type { LTISession } from '../interfaces/ltiSession.js';
+import type { DeepLinkingContentItem } from '../schemas/lti13/deepLinking/contentItem.schema.js';
+
+/**
+ * Deep Linking service for LTI 1.3.
+ * Generates signed JWT responses containing selected content items to return to the platform.
+ *
+ * @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,
+    private keyId = 'main',
+  ) {}
+
+  /**
+   * Creates a Deep Linking response with selected content items.
+   * Generates a signed JWT and returns an HTML form that auto-submits to the platform.
+   *
+   * @param session - Active LTI session containing Deep Linking configuration
+   * @param contentItems - Array of content items selected by the user
+   * @returns Promise resolving to an HTML string containing auto-submit form
+   * @throws {Error} When Deep Linking is not available for the session
+   *
+   * @example
+   * ```typescript
+   * const html = await deepLinkingService.createResponse(session, [
+   *   {
+   *     type: 'ltiResourceLink',
+   *     title: 'Quiz 1',
+   *     url: 'https://tool.example.com/quiz/1'
+   *   }
+   * ]);
+   * // Returns HTML form that auto-submits to platform
+   * ```
+   */
+  async createResponse(
+    session: LTISession,
+    contentItems: DeepLinkingContentItem[],
+  ): Promise<string> {
+    if (!session.services?.deepLinking) {
+      throw new Error('Deep Linking not available for this session');
+    }
+
+    this.logger.debug(
+      {
+        contentItemCount: contentItems.length,
+        returnUrl: session.services.deepLinking.returnUrl,
+      },
+      'Creating Deep Linking response',
+    );
+
+    const jwt = await this.createDeepLinkingJWT(session, contentItems);
+    return this.generateAutoSubmitForm(session.services.deepLinking.returnUrl, jwt);
+  }
+
+  /**
+   * Creates a signed JWT containing the Deep Linking response payload.
+   *
+   * @param session - Active LTI session with Deep Linking configuration
+   * @param contentItems - Array of selected content items
+   * @returns Promise resolving to a signed JWT string
+   */
+  private async createDeepLinkingJWT(
+    session: LTISession,
+    contentItems: DeepLinkingContentItem[],
+  ): Promise<string> {
+    const deepLinking = session.services!.deepLinking!;
+
+    const payload = {
+      iss: session.platform.clientId,
+      aud: session.platform.issuer,
+      exp: Math.floor(Date.now() / 1000) + 600,
+      iat: Math.floor(Date.now() / 1000),
+      nonce: crypto.randomUUID(),
+      'https://purl.imsglobal.org/spec/lti/claim/message_type': 'LtiDeepLinkingResponse',
+      'https://purl.imsglobal.org/spec/lti/claim/version': '1.3.0',
+      'https://purl.imsglobal.org/spec/lti/claim/deployment_id':
+        session.platform.deploymentId,
+      'https://purl.imsglobal.org/spec/lti-dl/claim/content_items': contentItems,
+      'https://purl.imsglobal.org/spec/lti-dl/claim/data': deepLinking.data,
+    };
+
+    return await new SignJWT(payload)
+      .setProtectedHeader({
+        alg: 'RS256',
+        typ: 'JWT',
+        kid: this.keyId,
+      })
+      .sign(this.keyPair.privateKey);
+  }
+
+  /**
+   * Generates an HTML form that auto-submits the Deep Linking response to the platform.
+   *
+   * @param returnUrl - Platform's Deep Linking return URL
+   * @param jwt - Signed JWT containing the response
+   * @returns HTML string with auto-submit form
+   */
+  private generateAutoSubmitForm(returnUrl: string, jwt: string): string {
+    return `
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Returning to platform...</title>
+</head>
+<body>
+  <form id="deepLinkingForm" method="POST" action="${returnUrl}">
+    <input type="hidden" name="JWT" value="${jwt}" />
+  </form>
+  <script>
+    document.getElementById('deepLinkingForm').submit();
+  </script>
+</body>
+</html>`;
+  }
+}

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,