@lti-tool/core 0.12.2 → 0.13.1

package/dist/schemas/lti13/deepLinking/contentItem.schema.js

@@ -0,0 +1,163 @@
+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,
+]);

package/dist/schemas/lti13/dynamicRegistration/ltiMessages.schema.d.ts

@@ -33,8 +33,8 @@ declare const LTIDeepLinkingMessageSchema: z.ZodObject<{
     supported_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         file: "file";
         ltiResourceLink: "ltiResourceLink";
-        html: "html";
         link: "link";
+        html: "html";
         image: "image";
     }>>>;
     supported_media_types: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -60,8 +60,8 @@ export declare const LTIMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     supported_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         file: "file";
         ltiResourceLink: "ltiResourceLink";
-        html: "html";
         link: "link";
+        html: "html";
         image: "image";
     }>>>;
     supported_media_types: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -86,8 +86,8 @@ export declare const LTIMessagesArraySchema: z.ZodArray<z.ZodDiscriminatedUnion<
     supported_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         file: "file";
         ltiResourceLink: "ltiResourceLink";
-        html: "html";
         link: "link";
+        html: "html";
         image: "image";
     }>>>;
     supported_media_types: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/schemas/lti13/dynamicRegistration/registrationResponse.schema.d.ts

@@ -57,8 +57,8 @@ export declare const RegistrationResponseSchema: z.ZodObject<{
             supported_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                 file: "file";
                 ltiResourceLink: "ltiResourceLink";
-                html: "html";
                 link: "link";
+                html: "html";
                 image: "image";
             }>>>;
             supported_media_types: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/schemas/lti13/dynamicRegistration/toolRegistrationPayload.schema.d.ts

@@ -28,8 +28,8 @@ declare const LTIToolConfigurationSchema: z.ZodObject<{
         supported_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
             file: "file";
             ltiResourceLink: "ltiResourceLink";
-            html: "html";
             link: "link";
+            html: "html";
             image: "image";
         }>>>;
         supported_media_types: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -87,8 +87,8 @@ export declare const ToolRegistrationPayloadSchema: z.ZodObject<{
             supported_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                 file: "file";
                 ltiResourceLink: "ltiResourceLink";
-                html: "html";
                 link: "link";
+                html: "html";
                 image: "image";
             }>>>;
             supported_media_types: z.ZodOptional<z.ZodArray<z.ZodString>>;

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

@@ -14,6 +14,13 @@ export declare class AGSService {
     private tokenService;
     private storage;
     private logger;
+    /**
+     * 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(tokenService: TokenService, storage: LTIStorage, logger: BaseLogger);
     /**
      * Submits a grade score to the platform using LTI Assignment and Grade Services.
@@ -108,6 +115,16 @@ export declare 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();
+     * ```
      */
     updateLineItem(session: LTISession, updateLineItem: UpdateLineItem): Promise<Response>;
     /**
@@ -116,6 +133,12 @@ export declare 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');
+     * ```
      */
     deleteLineItem(session: LTISession): Promise<Response>;
     private getAGSToken;

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

@@ -1 +1 @@
-{"version":3,"file":"ags.service.d.ts","sourceRoot":"","sources":["../../src/services/ags.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;AAC9D,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACf,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAC;AAGtF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;gBAFN,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,UAAU;IAG5B;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC;IAiCjF;;;;;;;;;;;;;OAaG;IACG,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;IA4BvD;;;;;;;;;;;;;OAaG;IACG,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;IAsB3D;;;;;;;;;;;;;OAaG;IACG,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;IAsBzD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,EACnB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,QAAQ,CAAC;IAuBpB;;;;;;;OAOG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,EACnB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,QAAQ,CAAC;IAuBpB;;;;;;OAMG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;YAqB9C,WAAW;YAeX,mBAAmB;CAalC"}
+{"version":3,"file":"ags.service.d.ts","sourceRoot":"","sources":["../../src/services/ags.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;AAC9D,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACf,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAC;AAGtF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,UAAU;IASnB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IAVhB;;;;;;OAMG;gBAEO,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,UAAU;IAG5B;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC;IAiCjF;;;;;;;;;;;;;OAaG;IACG,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;IA4BvD;;;;;;;;;;;;;OAaG;IACG,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;IAsB3D;;;;;;;;;;;;;OAaG;IACG,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;IAsBzD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,EACnB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,QAAQ,CAAC;IAuBpB;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,EACnB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,QAAQ,CAAC;IAuBpB;;;;;;;;;;;;OAYG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;YAqB9C,WAAW;YAeX,mBAAmB;CAalC"}

package/dist/services/ags.service.js

@@ -9,6 +9,13 @@ export class AGSService {
     tokenService;
     storage;
     logger;
+    /**
+     * 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(tokenService, storage, logger) {
         this.tokenService = tokenService;
         this.storage = storage;
@@ -193,6 +200,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, updateLineItem) {
         if (!session.services?.ags?.lineitem) {
@@ -216,6 +233,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) {
         if (!session.services?.ags?.lineitem) {

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

@@ -0,0 +1,61 @@
+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 declare class DeepLinkingService {
+    private keyPair;
+    private logger;
+    private keyId;
+    /**
+     * 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(keyPair: CryptoKeyPair, logger: BaseLogger, keyId?: string);
+    /**
+     * 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
+     * ```
+     */
+    createResponse(session: LTISession, contentItems: DeepLinkingContentItem[]): Promise<string>;
+    /**
+     * 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 createDeepLinkingJWT;
+    /**
+     * 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;
+}
+//# sourceMappingURL=deepLinking.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deepLinking.service.d.ts","sourceRoot":"","sources":["../../src/services/deepLinking.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oDAAoD,CAAC;AAEjG;;;;;GAKG;AACH,qBAAa,kBAAkB;IAS3B,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,KAAK;IAVf;;;;;;OAMG;gBAEO,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,UAAU,EAClB,KAAK,SAAS;IAGxB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,cAAc,CAClB,OAAO,EAAE,UAAU,EACnB,YAAY,EAAE,sBAAsB,EAAE,GACrC,OAAO,CAAC,MAAM,CAAC;IAiBlB;;;;;;OAMG;YACW,oBAAoB;IA6BlC;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;CAiB/B"}

package/dist/services/deepLinking.service.js

@@ -0,0 +1,109 @@
+import { SignJWT } from 'jose';
+/**
+ * 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 {
+    keyPair;
+    logger;
+    keyId;
+    /**
+     * 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(keyPair, logger, keyId = 'main') {
+        this.keyPair = keyPair;
+        this.logger = logger;
+        this.keyId = keyId;
+    }
+    /**
+     * 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, contentItems) {
+        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
+     */
+    async createDeepLinkingJWT(session, contentItems) {
+        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
+     */
+    generateAutoSubmitForm(returnUrl, jwt) {
+        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/dist/services/dynamicRegistration.service.d.ts

@@ -53,6 +53,13 @@ export declare class DynamicRegistrationService {
     private storage;
     private dynamicRegistrationConfig;
     private logger;
+    /**
+     * 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(storage: LTIStorage, dynamicRegistrationConfig: DynamicRegistrationConfig, logger: BaseLogger);
     /**
      * Fetches and validates the OpenID Connect configuration from an LTI platform during dynamic registration.

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

@@ -1 +1 @@
-{"version":3,"file":"dynamicRegistration.service.d.ts","sourceRoot":"","sources":["../../src/services/dynamicRegistration.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEvC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,gDAAgD,CAAC;AACpG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uEAAuE,CAAC;AAErH,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,oEAAoE,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oEAAoE,CAAC;AAS9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,0BAA0B;IAEnC,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,yBAAyB;IACjC,OAAO,CAAC,MAAM;gBAFN,OAAO,EAAE,UAAU,EACnB,yBAAyB,EAAE,yBAAyB,EACpD,MAAM,EAAE,UAAU;IAG5B;;;;;;;OAOG;IACG,0BAA0B,CAC9B,mBAAmB,EAAE,mBAAmB,GACvC,OAAO,CAAC,mBAAmB,CAAC;IAkC/B;;;;;;;;OAQG;IACG,2BAA2B,CAC/B,mBAAmB,EAAE,mBAAmB,EACxC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC;IAsClB;;;;;;;OAOG;IACG,2BAA2B,CAC/B,uBAAuB,EAAE,uBAAuB,GAC/C,OAAO,CAAC,MAAM,CAAC;IAoDlB;;;;;;OAMG;IACG,yBAAyB,CAC7B,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,6BAA6B,GAAG,SAAS,CAAC;IAQrD;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAoBrB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAoBnB;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;YAkClB,mCAAmC;IAgBjD,OAAO,CAAC,0BAA0B;CAiDnC"}
+{"version":3,"file":"dynamicRegistration.service.d.ts","sourceRoot":"","sources":["../../src/services/dynamicRegistration.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEvC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,gDAAgD,CAAC;AACpG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uEAAuE,CAAC;AAErH,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,oEAAoE,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oEAAoE,CAAC;AAS9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,0BAA0B;IASnC,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,yBAAyB;IACjC,OAAO,CAAC,MAAM;IAVhB;;;;;;OAMG;gBAEO,OAAO,EAAE,UAAU,EACnB,yBAAyB,EAAE,yBAAyB,EACpD,MAAM,EAAE,UAAU;IAG5B;;;;;;;OAOG;IACG,0BAA0B,CAC9B,mBAAmB,EAAE,mBAAmB,GACvC,OAAO,CAAC,mBAAmB,CAAC;IAkC/B;;;;;;;;OAQG;IACG,2BAA2B,CAC/B,mBAAmB,EAAE,mBAAmB,EACxC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC;IAsClB;;;;;;;OAOG;IACG,2BAA2B,CAC/B,uBAAuB,EAAE,uBAAuB,GAC/C,OAAO,CAAC,MAAM,CAAC;IAoDlB;;;;;;OAMG;IACG,yBAAyB,CAC7B,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,6BAA6B,GAAG,SAAS,CAAC;IAQrD;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAoBrB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAoBnB;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;YAkClB,mCAAmC;IAgBjD,OAAO,CAAC,0BAA0B;CAiDnC"}

package/dist/services/dynamicRegistration.service.js

@@ -48,6 +48,13 @@ export class DynamicRegistrationService {
     storage;
     dynamicRegistrationConfig;
     logger;
+    /**
+     * 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(storage, dynamicRegistrationConfig, logger) {
         this.storage = storage;
         this.dynamicRegistrationConfig = dynamicRegistrationConfig;

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

@@ -12,14 +12,28 @@ export declare class NRPSService {
     private tokenService;
     private storage;
     private logger;
+    /**
+     * 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(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
+     * @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);
+     * ```
      */
     getMembers(session: LTISession): Promise<Response>;
     private getNRPSToken;

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

@@ -1 +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"}
+{"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;IASpB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IAVhB;;;;;;OAMG;gBAEO,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,UAAU;IAG5B;;;;;;;;;;;;;;OAcG;IACG,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;YAsB1C,YAAY;YAeZ,oBAAoB;CAanC"}

package/dist/services/nrps.service.js

@@ -9,6 +9,13 @@ export class NRPSService {
     tokenService;
     storage;
     logger;
+    /**
+     * 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(tokenService, storage, logger) {
         this.tokenService = tokenService;
         this.storage = storage;
@@ -19,8 +26,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) {
         if (!session.services?.nrps?.membershipUrl) {

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

@@ -4,6 +4,8 @@
  *
  * 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 declare class TokenService {
     private keyPair;
@@ -20,7 +22,7 @@ export declare 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
      */
     createClientAssertion(clientId: string, tokenUrl: string): Promise<string>;
     /**
@@ -29,7 +31,8 @@ export declare 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
      */
     getBearerToken(clientId: string, tokenUrl: string, scope: string): Promise<string>;
 }

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;CA6BnB"}
+{"version":3,"file":"token.service.d.ts","sourceRoot":"","sources":["../../src/services/token.service.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;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;;;;;;;;OAQG;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

@@ -5,6 +5,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 {
     keyPair;
@@ -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, tokenUrl) {
         return await new SignJWT({
@@ -48,7 +50,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, tokenUrl, scope) {
         const assertion = await this.createClientAssertion(clientId, tokenUrl);