stemcstudio-tunnel/build/index.d.ts

Allows STEMCstudio programs to post and receive messages when embedded in an IFrame and an LTI 1.3 LMS.

/**
 * A subscription that may be ended.
 */
interface Subscription {
    /**
     * Ends the subscription.
     */
    dispose(): void;
}
/**
 * A communication channel between a STEMCstudio or STEMCviewer program and a page with an iframe embedded within it.
 */
interface Tunnel {
    /**
     * Subscribes to window events of type 'message'.
     * @param handler a JavaScript function that receives a notification when an event of the 'message' type occurs.
     * @returns A subscription object that may be ended by calling the dispose() method.
     */
    subscribe<T>(handler: (this: Window, event: MessageEvent<T>) => void): Subscription;
    /**
     * Safely enables cross-origin communication between Window objects; e.g., between a page and an iframe embedded within it.
     * @param message Data to be sent to the other window.
     * @param transfer A sequence of Transferable objects that are transferred with the message.
     */
    postMessage<T>(message: T, transfer?: Transferable[]): void;
    /**
     * @hidden
     */
    setWindow($window: TunnelWindow): void;
}
/**
 * Used for testing.
 * @hidden
 */
interface TunnelWindowParent {
    postMessage(message: unknown, targetOrigin: string, transfer?: Transferable[]): void;
}
/**
 * Used for testing.
 * @hidden
 */
interface TunnelWindow {
    parent: TunnelWindowParent;
    addEventListener<T>(type: 'message', handler: (event: MessageEvent<T>) => void): void;
    removeEventListener<T>(type: 'message', handler: (event: MessageEvent<T>) => void): void;
}
/**
 * An Item in the Gradebook.
 * If a student is represented as a row in the Gradebook then an Item is a column in the Gradebook.
 * An Item is associated with a Learning Activity.
 * There can be one or more items for a given Learning Activity.
 */
interface Item {
    /**
     * The unique identifier for the Item assigned by the LMS.
     */
    id: string;
    /**
     * The maximum score for this line item.
     * Maximum score must be a numeric non null value, strictly greater than 0.
     * A default value may be set by the LMS.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#scoremaximum
     */
    scoreMaximum: number;
    /**
     * The name of the activity that is presented in the LMS.
     * The label is a short string with a human readable text for the line item.
     * It must be specified and not blank when posted by the tool.
     * A platform must always include the label, although it may be blank if there is no label for that line item.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#label
     */
    label: string;
    /**
     * The tag set by the Tool when the Item was created.
     * A tool MAY further qualify a line item by setting a value to tag.
     * The attribute is a string. For example, one assignment resource may have 2 line items, one with tag as 'grade' and the other tagged as 'originality'.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#tag
     */
    tag?: string;
    /**
     * Assigned by the LMS.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#resourcelinkid-and-binding-a-line-item-to-a-resource-link
     */
    resourceLinkId?: string;
    /**
     * The resource identifier used by STEMCstudio to retrive the snapshot of the project.
     * This snapshot was created at the time the Dynamic Linking was performed.
     * It may be set by the Tool when an Item is created.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#tool-resource-identifier-resourceid
     */
    resourceId?: string;
    /**
     * Assigned by the LMS.
     */
    ltiLinkId?: string;
    /**
     * The start date and time for the Learning Activity in ISO8601 format.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#startdatetime
     */
    startDateTime?: string;
    /**
     * The end date and time for the Learning Activity in ISO8601 format.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#enddatetime
     */
    endDateTime?: string;
}
/**
 * The Result is the current score within the Tool Consumer for the line item and user.
 * i.e. the value currently showing in the cell for that column and user in a typical tabular gradebook.
 * This value can only be read by the tool, as the platform has the final say on what should be a student
 * final score; for example, an instructor may force a grade through a manual entry directly in the gradebook.
 * Or a modifier may be applied (late work, ...).
 */
interface Result {
    /**
     * The unique identifier for the Result assigned by the LMS.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#id
     */
    id: string;
    /**
     * The unique identifier for the user assigned by the LMS.
     * The userId identifies the recipient of the Score (usually a student).
     * The userId MUST be present and MUST be the same as the resource link LTI parameter 'user_id'.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#userid
     */
    userId: string;
    /**
     * The current score for this user.
     * The value must be a numeric value.
     * If no value exists, this attribute may be omitted, or have an explicit null value.
     * resultScore = resultMaximum * (Score.scoreGiven / Score.scoreMaximum)
     * http://www.imsglobal.org/spec/lti-ags/v2p0#resultscore
     */
    resultScore: number;
    /**
     * The maximum score value defined by the LMS for the Learning Activity.
     * The 'resultMaximum' value MUST be a positive number (with 0 considered a negative number);
     * if no value is specified, then a default maximum value of 1 must be used.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#resultmaximum
     */
    resultMaximum: number;
    /**
     * The Item identifier assigned by the LMS.
     * URL identifying the Line Item to which this result belongs.
     * Must be the same as the line item id and the value of the lineitem claim when included in the LTI message.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#scoreof
     */
    scoreOf: string;
    /**
     * The date and time of the score submission in ISO8601 format (YYYY-MM-DD 'T' HH:MM:SS '+/-' HH:MM)
     */
    timestamp: string;
    /**
     * The comment given when the score was submitted.
     * The current value for the comment.
     * The value must be a string.
     * If no value exists, this attribute may be omitted, blank or have an explicit null value.
     */
    comment?: string;
}
/**
 * The Score for a Learning Activity that is submitted to the Gradebook of the LMS.
 * The Score is the last score (or status change) the user got within the tool itself.
 * It is published to the platform so that it may be used to update the current result.
 * This value is write-only.
 */
interface Score {
    /**
     * The score given by the Learning Tool for the submission to the Gradebook Item for a user.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#scoregiven-and-scoremaximum
     */
    scoreGiven?: number;
    /**
     * The maximum score defined by the Learning Tool for the submission to the Gradebook Item for a user.
     * http://www.imsglobal.org/spec/lti-ags/v2p0#scoregiven-and-scoremaximum
     */
    scoreMaximum?: number;
    /**
     * Set to 'Completed' for a final score update.
     *
     * http://www.imsglobal.org/spec/lti-ags/v2p0#activityprogress
     */
    activityProgress: 'Initialized' | 'Started' | 'InProgress' | 'Submitted' | 'Completed';
    /**
     * Set to 'FullyGraded' for a final score update.
     *
     * http://www.imsglobal.org/spec/lti-ags/v2p0#gradingprogress
     */
    gradingProgress: 'FullyGraded' | 'Pending' | 'PendingManual' | 'Failed' | 'NotReady';
    /**
     * The comment for the score that is assigned by the Learning Tool.
     * A score object MAY include a comment.
     * A comment value MUST be a string in plain text format.
     * comment is intended to be seen by both the student and the instructors.
     * This specification does not support an history of comments; the platform MUST update its comment with every score update.
     * If a score update does not contain a comment, a blank or null, then the comment value MUST be cleared in the platform if the previously recorded comment was also a comment sent from the tool.
     */
    comment?: string;
}
/**
 *
 */
type Role = "Administrator" | "ContentDeveloper" | "Instructor" | "Learner" | "Mentor" | "Manager" | "Member" | "Officer" | "http://purl.imsglobal.org/vocab/lis/v2/system/person#Administrator" | "http://purl.imsglobal.org/vocab/lis/v2/system/person#None" | "http://purl.imsglobal.org/vocab/lis/v2/system/person#AccountAdmin" | "http://purl.imsglobal.org/vocab/lis/v2/system/person#Creator" | "http://purl.imsglobal.org/vocab/lis/v2/system/person#SysAdmin" | "http://purl.imsglobal.org/vocab/lis/v2/system/person#SysSupport" | "http://purl.imsglobal.org/vocab/lis/v2/system/person#User" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Administrator" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Faculty" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Guest" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#None" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Other" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Staff" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Student" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Alumni" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Instructor" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Learner" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Member" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Mentor" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Observer" | "http://purl.imsglobal.org/vocab/lis/v2/institution/person#ProspectiveStudent" | "http://purl.imsglobal.org/vocab/lis/v2/membership#Administrator" | "http://purl.imsglobal.org/vocab/lis/v2/membership#ContentDeveloper" | "http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor" | "http://purl.imsglobal.org/vocab/lis/v2/membership#Learner" | "http://purl.imsglobal.org/vocab/lis/v2/membership#Mentor" | "http://purl.imsglobal.org/vocab/lis/v2/membership#Manager" | "http://purl.imsglobal.org/vocab/lis/v2/membership#Member" | "http://purl.imsglobal.org/vocab/lis/v2/membership#Officer";
/**
 * A member of a course section.
 */
interface Member {
    /**
     * The status of the member.
     */
    status: 'Active' | 'Inactive';
    /**
     * An array of strings describing the roles of the member. e.g. ["Learner"].
     */
    roles: Role[];
    /**
     * The unique identifier for the associated user assigned by the LMS.
     */
    user_id: string;
    /**
     *
     */
    lis_person_sourceid: string;
    /**
     * The display name for the user, usually Member.given_name + " " + Member.family_name.
     */
    name: string;
    /**
     * The first name of the user.
     */
    given_name: string;
    /**
     * The surname of the user.
     */
    family_name: string;
    /**
     * The email address of the user.
     */
    email: string;
    /**
     * message is only returned for resource link requests.
     */
    message?: {
        'https://purl.imsglobal.org/spec/lti/claim/message_type': 'LtiResourceLinkRequest' | 'LtiDeepLinkingRequest';
    }[];
}
/**
 * The context of a Learning Activity. This might be a course.
 */
interface Context {
    id: string;
    /**
     * The short name for the course or context.
     */
    label: string;
    /**
     * The long name for the course or context.
     */
    title: string;
    /**
     * e.g. ["CourseSection"]
     */
    type?: string[];
}
/**
 * Corresponds to the membership container media type.
 */
interface ContextMembership {
    /**
     * The unique identifier for the membership of the learning context assigned by the LMS.
     */
    id: string;
    /**
     * The context of the membership. This will usually be a course.
     */
    context: Context;
    /**
     * The members of the course.
     */
    members: Member[];
}
/**
 * The Gradebook API of the Learning Management System.
 */
interface Gradebook {
    /**
     * Creates a new Item in the Gradebook.
     * @param item The data for the new Gradebook Item.
     */
    createItem(item: Omit<Item, "id" | "ltiLinkId" | "resourceLinkId">): Promise<Item>;
    /**
     * Retrieves the Item(s) in the Gradebook for the current Learning Activity.
     */
    getItems(): Promise<Item[]>;
    /**
     * Retrieves the results for the specified Item in the Gradebook.
     * @param itemId The unique identifier for the Item in the Gradebook.
     */
    getResults(itemId: string): Promise<Result[]>;
    /**
     * Submits a score to the Gradebook for a specified Gradebook Item.
     * @param itemId The unique identifier for the Item in the Gradebook.
     * @param score The score that is being submitted.
     */
    submitScore(itemId: string, score: Score): Promise<void>;
}
/**
 * The Cohort API of the Learning Management System.
 */
interface Cohort {
    /**
     * Retrieves the membership of the current learning context.
     */
    getMembers(): Promise<ContextMembership>;
}
/**
 * The options for the User.alert method.
 */
interface AlertOptions {
    /**
     * The title of the dialog.
     */
    title: string;
    /**
     * The top-level message text of the dialog.
     */
    message: string;
}
/**
 * The options for the User.confirm method.
 */
interface ConfirmOptions {
    /**
     * The title of the dialog.
     */
    title: string;
    /**
     * The top-level message text of the dialog.
     */
    message: string;
    /**
     * The cancel button text. Defaults to 'Cancel'.
     */
    cancelButtonText?: string;
    /**
     * The action button text. Defaults to 'OK'.
     */
    actionButtonText?: string;
}
/**
 * The options for the User.prompt method.
 */
interface PromptOptions {
    /**
     * The title of the dialog.
     */
    title: string;
    /**
     * The top-level message text of the dialog.
     */
    message: string;
    /**
     * The text that is used to initialized the input tag.
     */
    text: string;
    /**
     * The text that is used for the label that is provided for the input tag.
     */
    label: string;
    /**
     * The text that is used to provide a hint for a correct input.
     */
    hint: string;
    /**
     * The text that is used for the cancel button.
     */
    cancelButtonText?: string;
    /**
     * The text that is used for the action button (not the cancel button)
     */
    actionButtonText?: string;
}
/**
 * The User API for requesting feedback from the current user through standard dialogs.
 */
interface User {
    /**
     * Presents a modal dialog to the user containing an alert message.
     * @param options The configuration options for the dialog.
     */
    alert(options: AlertOptions): Promise<boolean>;
    /**
     * Presents a modal dialog to the user containing a confirmation request for an upcoming action.
     * The user has the abilty to confirm that the action should proceed or to cancel the action.
     * @param options The configuration options for the dialog.
     */
    confirm(options: ConfirmOptions): Promise<boolean>;
    /**
     * Presents a modal dialog to the user promting for textual information.
     * @param options The configuration options for the dialog.
     */
    prompt(options: PromptOptions): Promise<string>;
}
/**
 * Singleton instance of Tunnel for communicating with the host web page.
 */
declare const tunnel: Tunnel;
/**
 * The current Gradebook instance.
 */
declare const gradebook: Gradebook;
/**
 * The current Organization instance.
 */
declare const cohort: Cohort;
/**
 * The Modal Dialog Service instance provided by the STEMCstudio parent window.
 */
declare const user: User;

export { AlertOptions, Cohort, ConfirmOptions, Context, ContextMembership, Gradebook, Item, Member, PromptOptions, Result, Role, Score, Subscription, Tunnel, TunnelWindow, TunnelWindowParent, User, cohort, gradebook, tunnel, user };