@moodle-next/next 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,153 @@
+type MoodleSession = {
+    token: string;
+    userId: number;
+    username: string;
+    fullName: string;
+    email?: string;
+    userPictureUrl?: string;
+    canManagePlatform?: boolean;
+    canManageOwnFiles?: boolean;
+    expiresAt: number;
+};
+type MoodleSessionConfig = {
+    /** Cookie name. Default: `"moodle_session"` */
+    cookieName?: string;
+    /** Session lifetime in seconds. Default: `28800` (8 hours) */
+    durationSeconds?: number;
+    /** Path to redirect unauthenticated requests to. Default: `"/"` */
+    loginPath?: string;
+    /** Path to redirect when the Moodle token has expired. Default: `"/auth/session-expired"` */
+    expiredSessionPath?: string;
+    /**
+     * Session encryption secret. Falls back to `process.env.APP_SESSION_SECRET`.
+     * Must be set before calling any session function.
+     */
+    sessionSecret?: string;
+};
+declare function configureMoodleSession(config: MoodleSessionConfig): void;
+declare function createSession(session: Omit<MoodleSession, 'expiresAt'>): Promise<void>;
+declare function getSession(): Promise<MoodleSession | null>;
+declare function requireSession(): Promise<MoodleSession>;
+declare function clearSession(): Promise<void>;
+declare function redirectToExpiredSession(): never;
+declare function redirectIfSessionExpired(error: unknown): void;
+declare function clearSessionIfAuthenticationError(error: unknown): Promise<boolean>;
+declare function getSessionOrUnauthorizedResponse(): Promise<{
+    session: MoodleSession;
+    response: null;
+} | {
+    session: null;
+    response: Response;
+}>;
+declare function clearSessionAndReturnUnauthorized(): Promise<Response>;
+
+type MoodleBranding = {
+    siteName: string;
+    siteDescription?: string;
+    siteUrl: string;
+    logoUrl?: string;
+    compactLogoUrl?: string;
+};
+declare const getMoodleBranding: () => Promise<MoodleBranding>;
+declare function getSiteForceLogin(): Promise<boolean>;
+declare function getSiteGlobalSearchEnabled(): Promise<boolean>;
+declare function getSiteMessagingEnabled(): Promise<boolean>;
+
+type GetSession$1 = () => Promise<{
+    token: string;
+} | null>;
+type OnAuthFailure$1 = () => Promise<Response> | Response;
+/**
+ * Creates GET and HEAD handlers for proxying authenticated Moodle media files.
+ *
+ * Mount these at a route like `app/api/moodle-media/route.ts`:
+ * ```ts
+ * import { createMoodleMediaHandler } from '@moodle-next/next';
+ * import { getSession } from '@/lib/session';
+ * export const { GET, HEAD } = createMoodleMediaHandler(getSession);
+ * ```
+ */
+declare function createMoodleMediaHandler(getSession: GetSession$1, onAuthFailure?: OnAuthFailure$1): {
+    GET: (request: Request) => Promise<Response>;
+    HEAD: (request: Request) => Promise<Response>;
+};
+
+type GetSession = () => Promise<{
+    token: string;
+} | null>;
+type OnAuthFailure = () => Promise<Response> | Response;
+/**
+ * Creates GET and HEAD handlers for proxying authenticated Moodle SCORM packages.
+ *
+ * Mount these at a route like `app/api/moodle-scorm/[base]/[[...path]]/route.ts`:
+ * ```ts
+ * import { createMoodleScormHandler } from '@moodle-next/next';
+ * import { getSession } from '@/lib/session';
+ * export const { GET, HEAD } = createMoodleScormHandler(getSession);
+ * ```
+ *
+ * The optional `injectIntoHtml` callback lets you intercept HTML responses and
+ * inject a SCORM runtime shim before the content is returned to the browser.
+ */
+declare function createMoodleScormHandler(getSession: GetSession, options?: {
+    onAuthFailure?: OnAuthFailure;
+    /** Called when the upstream response is an HTML document. Return modified HTML. */
+    injectIntoHtml?: (html: string, requestUrl: URL) => string | Promise<string>;
+}): {
+    GET: (request: Request, context: {
+        params: Promise<{
+            base: string;
+            path?: string[];
+        }>;
+    }) => Promise<Response>;
+    HEAD: (request: Request, context: {
+        params: Promise<{
+            base: string;
+            path?: string[];
+        }>;
+    }) => Promise<Response>;
+};
+
+/**
+ * Creates GET and HEAD handlers for serving the Moodle site logo (with SVG fallback).
+ *
+ * Mount these at a route like `app/api/moodle-brand-logo/route.ts`:
+ * ```ts
+ * import { createMoodleBrandLogoHandler } from '@moodle-next/next';
+ * export const { GET, HEAD } = createMoodleBrandLogoHandler();
+ * ```
+ *
+ * Accepts `?variant=full` (default) or `?variant=compact`.
+ */
+declare function createMoodleBrandLogoHandler(): {
+    GET: (request: Request) => Promise<Response>;
+    HEAD: (request: Request) => Promise<Response>;
+};
+
+/**
+ * Returns a URL for the media proxy route handler.
+ * Mount `createMoodleMediaHandler()` at `basePath` in your Next.js app.
+ */
+declare function getMoodleMediaProxyUrl(rawUrl?: string, basePath?: string): string | undefined;
+/**
+ * Returns a URL for the SCORM proxy route handler.
+ * Mount `createMoodleScormHandler()` at `basePath/[base]/[[...path]]` in your Next.js app.
+ */
+declare function getMoodleScormProxyUrl(rawUrl?: string, basePath?: string): string | undefined;
+/**
+ * Returns a URL for the brand logo proxy route handler.
+ * Mount `createMoodleBrandLogoHandler()` at `basePath` in your Next.js app.
+ */
+declare function getMoodleBrandLogoProxyUrl(variant?: 'full' | 'compact', basePath?: string): string;
+
+/**
+ * Validates that a return path is a relative URL within an allowed section
+ * to prevent open redirect attacks.
+ *
+ * @param rawPath - The raw path to validate (typically from a query param).
+ * @param fallback - The fallback path if `rawPath` is invalid.
+ * @param allowedPrefixes - Path prefixes to accept. Defaults to `["/"]` (any relative path).
+ */
+declare function sanitizeReturnPath(rawPath: string | null | undefined, fallback: string, allowedPrefixes?: string[]): string;
+
+export { type MoodleBranding, type MoodleSession, clearSession, clearSessionAndReturnUnauthorized, clearSessionIfAuthenticationError, configureMoodleSession, createMoodleBrandLogoHandler, createMoodleMediaHandler, createMoodleScormHandler, createSession, getMoodleBrandLogoProxyUrl, getMoodleBranding, getMoodleMediaProxyUrl, getMoodleScormProxyUrl, getSession, getSessionOrUnauthorizedResponse, getSiteForceLogin, getSiteGlobalSearchEnabled, getSiteMessagingEnabled, redirectIfSessionExpired, redirectToExpiredSession, requireSession, sanitizeReturnPath };

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+type MoodleSession = {
+    token: string;
+    userId: number;
+    username: string;
+    fullName: string;
+    email?: string;
+    userPictureUrl?: string;
+    canManagePlatform?: boolean;
+    canManageOwnFiles?: boolean;
+    expiresAt: number;
+};
+type MoodleSessionConfig = {
+    /** Cookie name. Default: `"moodle_session"` */
+    cookieName?: string;
+    /** Session lifetime in seconds. Default: `28800` (8 hours) */
+    durationSeconds?: number;
+    /** Path to redirect unauthenticated requests to. Default: `"/"` */
+    loginPath?: string;
+    /** Path to redirect when the Moodle token has expired. Default: `"/auth/session-expired"` */
+    expiredSessionPath?: string;
+    /**
+     * Session encryption secret. Falls back to `process.env.APP_SESSION_SECRET`.
+     * Must be set before calling any session function.
+     */
+    sessionSecret?: string;
+};
+declare function configureMoodleSession(config: MoodleSessionConfig): void;
+declare function createSession(session: Omit<MoodleSession, 'expiresAt'>): Promise<void>;
+declare function getSession(): Promise<MoodleSession | null>;
+declare function requireSession(): Promise<MoodleSession>;
+declare function clearSession(): Promise<void>;
+declare function redirectToExpiredSession(): never;
+declare function redirectIfSessionExpired(error: unknown): void;
+declare function clearSessionIfAuthenticationError(error: unknown): Promise<boolean>;
+declare function getSessionOrUnauthorizedResponse(): Promise<{
+    session: MoodleSession;
+    response: null;
+} | {
+    session: null;
+    response: Response;
+}>;
+declare function clearSessionAndReturnUnauthorized(): Promise<Response>;
+
+type MoodleBranding = {
+    siteName: string;
+    siteDescription?: string;
+    siteUrl: string;
+    logoUrl?: string;
+    compactLogoUrl?: string;
+};
+declare const getMoodleBranding: () => Promise<MoodleBranding>;
+declare function getSiteForceLogin(): Promise<boolean>;
+declare function getSiteGlobalSearchEnabled(): Promise<boolean>;
+declare function getSiteMessagingEnabled(): Promise<boolean>;
+
+type GetSession$1 = () => Promise<{
+    token: string;
+} | null>;
+type OnAuthFailure$1 = () => Promise<Response> | Response;
+/**
+ * Creates GET and HEAD handlers for proxying authenticated Moodle media files.
+ *
+ * Mount these at a route like `app/api/moodle-media/route.ts`:
+ * ```ts
+ * import { createMoodleMediaHandler } from '@moodle-next/next';
+ * import { getSession } from '@/lib/session';
+ * export const { GET, HEAD } = createMoodleMediaHandler(getSession);
+ * ```
+ */
+declare function createMoodleMediaHandler(getSession: GetSession$1, onAuthFailure?: OnAuthFailure$1): {
+    GET: (request: Request) => Promise<Response>;
+    HEAD: (request: Request) => Promise<Response>;
+};
+
+type GetSession = () => Promise<{
+    token: string;
+} | null>;
+type OnAuthFailure = () => Promise<Response> | Response;
+/**
+ * Creates GET and HEAD handlers for proxying authenticated Moodle SCORM packages.
+ *
+ * Mount these at a route like `app/api/moodle-scorm/[base]/[[...path]]/route.ts`:
+ * ```ts
+ * import { createMoodleScormHandler } from '@moodle-next/next';
+ * import { getSession } from '@/lib/session';
+ * export const { GET, HEAD } = createMoodleScormHandler(getSession);
+ * ```
+ *
+ * The optional `injectIntoHtml` callback lets you intercept HTML responses and
+ * inject a SCORM runtime shim before the content is returned to the browser.
+ */
+declare function createMoodleScormHandler(getSession: GetSession, options?: {
+    onAuthFailure?: OnAuthFailure;
+    /** Called when the upstream response is an HTML document. Return modified HTML. */
+    injectIntoHtml?: (html: string, requestUrl: URL) => string | Promise<string>;
+}): {
+    GET: (request: Request, context: {
+        params: Promise<{
+            base: string;
+            path?: string[];
+        }>;
+    }) => Promise<Response>;
+    HEAD: (request: Request, context: {
+        params: Promise<{
+            base: string;
+            path?: string[];
+        }>;
+    }) => Promise<Response>;
+};
+
+/**
+ * Creates GET and HEAD handlers for serving the Moodle site logo (with SVG fallback).
+ *
+ * Mount these at a route like `app/api/moodle-brand-logo/route.ts`:
+ * ```ts
+ * import { createMoodleBrandLogoHandler } from '@moodle-next/next';
+ * export const { GET, HEAD } = createMoodleBrandLogoHandler();
+ * ```
+ *
+ * Accepts `?variant=full` (default) or `?variant=compact`.
+ */
+declare function createMoodleBrandLogoHandler(): {
+    GET: (request: Request) => Promise<Response>;
+    HEAD: (request: Request) => Promise<Response>;
+};
+
+/**
+ * Returns a URL for the media proxy route handler.
+ * Mount `createMoodleMediaHandler()` at `basePath` in your Next.js app.
+ */
+declare function getMoodleMediaProxyUrl(rawUrl?: string, basePath?: string): string | undefined;
+/**
+ * Returns a URL for the SCORM proxy route handler.
+ * Mount `createMoodleScormHandler()` at `basePath/[base]/[[...path]]` in your Next.js app.
+ */
+declare function getMoodleScormProxyUrl(rawUrl?: string, basePath?: string): string | undefined;
+/**
+ * Returns a URL for the brand logo proxy route handler.
+ * Mount `createMoodleBrandLogoHandler()` at `basePath` in your Next.js app.
+ */
+declare function getMoodleBrandLogoProxyUrl(variant?: 'full' | 'compact', basePath?: string): string;
+
+/**
+ * Validates that a return path is a relative URL within an allowed section
+ * to prevent open redirect attacks.
+ *
+ * @param rawPath - The raw path to validate (typically from a query param).
+ * @param fallback - The fallback path if `rawPath` is invalid.
+ * @param allowedPrefixes - Path prefixes to accept. Defaults to `["/"]` (any relative path).
+ */
+declare function sanitizeReturnPath(rawPath: string | null | undefined, fallback: string, allowedPrefixes?: string[]): string;
+
+export { type MoodleBranding, type MoodleSession, clearSession, clearSessionAndReturnUnauthorized, clearSessionIfAuthenticationError, configureMoodleSession, createMoodleBrandLogoHandler, createMoodleMediaHandler, createMoodleScormHandler, createSession, getMoodleBrandLogoProxyUrl, getMoodleBranding, getMoodleMediaProxyUrl, getMoodleScormProxyUrl, getSession, getSessionOrUnauthorizedResponse, getSiteForceLogin, getSiteGlobalSearchEnabled, getSiteMessagingEnabled, redirectIfSessionExpired, redirectToExpiredSession, requireSession, sanitizeReturnPath };