@crimson-education/sdk 0.2.0

package/dist/core/types.d.ts

@@ -0,0 +1,402 @@
+import type { OAuthConfig, TokenStorage } from "./auth/types";
+/**
+ * OAuth-specific configuration for CrimsonClient
+ */
+export interface CrimsonOAuthConfig extends Omit<OAuthConfig, "authorizationEndpoint" | "tokenEndpoint" | "revocationEndpoint"> {
+    /**
+     * Custom token storage implementation
+     * Defaults to localStorage in browser
+     */
+    storage?: TokenStorage;
+    /**
+     * Enable automatic token refresh
+     * @default true
+     */
+    autoRefresh?: boolean;
+}
+/**
+ * Base configuration for CrimsonClient
+ */
+export interface CrimsonClientConfigBase {
+    /**
+     * Crimson API base URL
+     */
+    apiUrl: string;
+    /**
+     * Authorization scheme for the Authorization header
+     * @default "Bearer"
+     */
+    authScheme?: string;
+    /**
+     * Client application identifier for API tracking.
+     * Examples: 'new-roadmap', 'capstone', 'admin-dashboard'
+     */
+    clientId?: string;
+    /**
+     * SDK version override. Defaults to the SDK package version.
+     */
+    clientVersion?: string;
+}
+/**
+ * Configuration using a token provider function
+ */
+export interface CrimsonClientConfigWithToken extends CrimsonClientConfigBase {
+    /**
+     * Function to get the current authentication token
+     */
+    getToken: () => string | Promise<string>;
+    oauth?: never;
+}
+/**
+ * Configuration using OAuth authentication
+ */
+export interface CrimsonClientConfigWithOAuth extends CrimsonClientConfigBase {
+    /**
+     * OAuth configuration for authentication
+     */
+    oauth: CrimsonOAuthConfig;
+    getToken?: never;
+}
+/**
+ * CrimsonClient configuration
+ * Either provide a getToken function OR oauth configuration, not both
+ */
+export type CrimsonClientConfig = CrimsonClientConfigWithToken | CrimsonClientConfigWithOAuth;
+export interface TaskResource {
+    id?: string;
+    title: string;
+    type: "Link" | "Video" | "Upload";
+    url: string;
+    mediaType?: string;
+    orderIndex?: number;
+}
+export interface Task {
+    id: string;
+    /** Task title (displayed as the task name) */
+    name: string;
+    status: "PLANNED" | "SKIPPED" | "DONE" | string;
+    date: string;
+    roadmapMissionId: string;
+    userId: string;
+    creatorId?: string;
+    roadmapId?: string;
+    isComplete?: boolean;
+    dueDate?: string | null;
+    missionId?: string | null;
+    linkId?: string | null;
+    finishedAt?: string | null;
+    /** Task title (same as name, maps to description field in API) */
+    description?: string;
+    /** Task body/description content (maps to content field in API) */
+    content?: string;
+    /** Task attachments/resources */
+    resources?: TaskResource[];
+    /** Parent mission info (when returned from getActionItemsByRoadmapId) */
+    mission?: {
+        id: string;
+        title: string;
+        linkId?: string;
+    };
+}
+export interface Mission {
+    id: string;
+    title: string;
+    description?: string;
+    status: string;
+    startAt?: string;
+    dueDate?: string;
+    category?: string;
+    subcategory?: string;
+    roadmapId: string;
+    userId?: string;
+    linkId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    tasks?: Task[];
+    actionItems?: Task[];
+}
+export interface MissionsCategory {
+    category: string;
+    missionCount: number;
+    missions: Mission[];
+}
+export interface ApiResponse<T> {
+    data: T;
+}
+export interface RoadmapCategory {
+    id: string;
+    name: string;
+    description?: string;
+    color: string;
+    status: string;
+    default?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface RoadmapContext {
+    roadmapId: string;
+    userId: string;
+    categories: RoadmapCategory[];
+    id?: string;
+}
+export interface PaginationParams {
+    start?: number;
+    limit?: number;
+}
+export interface PaginationMeta {
+    total: number;
+    start: number;
+    limit: number;
+    hasMore: boolean;
+}
+export interface PaginatedResult<T> {
+    data: T[];
+    pagination: PaginationMeta;
+}
+export interface TemplateTaskResource {
+    id: string;
+    title: string;
+    type: string;
+    url: string;
+    mediaType?: string;
+    orderIndex?: number;
+}
+export interface TemplateMissionResource {
+    id: string;
+    title: string;
+    type: string;
+    url: string;
+    orderIndex?: number;
+}
+export interface TemplateTask {
+    id: string;
+    description: string;
+    content?: string;
+    type?: string;
+    status?: string;
+    dueDate?: string;
+    startAt?: string;
+    missionId?: string;
+    mission?: {
+        id: string;
+        title: string;
+        category?: string;
+        subcategory?: string;
+    };
+    resources?: TemplateTaskResource[];
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface TemplateMission {
+    id: string;
+    linkId?: string;
+    title: string;
+    description?: string;
+    category?: string;
+    secondaryCategory?: string;
+    subcategory?: string;
+    status?: string;
+    actionItemCount?: number;
+    actionItems?: TemplateTask[];
+    resources?: TemplateMissionResource[];
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface MissionDetail {
+    id: string;
+    linkId?: string;
+    title: string;
+    description?: string;
+    category?: string;
+    secondaryCategory?: string;
+    subcategory?: string;
+    status?: string;
+    dueDate?: string;
+    startAt?: string;
+    finishedAt?: string;
+    creatorId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    actionItemCount?: number;
+    memberCount?: number;
+    members?: string[];
+    integrationSource?: string;
+    attr?: string;
+    actionItems?: Array<{
+        id: string;
+        description: string;
+        content?: string;
+        status?: string;
+        dueDate?: string;
+        startAt?: string;
+        finishedAt?: string;
+        type?: string;
+        category?: string;
+        taskGroup?: string;
+        attr?: string;
+        resources?: TemplateTaskResource[];
+    }>;
+    resources?: TemplateMissionResource[];
+}
+export interface AssignBulkMissionInput {
+    studentUid: string;
+    templateMission: {
+        id: string;
+        roadmapId: string;
+        tenant: string;
+        startAt: string;
+        dueDate: string;
+        templateTasks: Array<{
+            id: string;
+            dueDate?: string;
+        }>;
+    };
+}
+export interface AssignBulkTaskInput {
+    studentUid: string;
+    tasks: Array<{
+        id: string;
+        dueDate?: string;
+        mission: {
+            id?: string;
+            roadmapId: string;
+            tenant: string;
+            startAt: string;
+            dueDate: string;
+            category?: string;
+            subcategory?: string;
+            title?: string;
+            description?: string;
+            secondaryCategory?: string;
+        };
+    }>;
+}
+export interface ActionItemResource {
+    id: string;
+    actionItemId: string;
+    title: string;
+    type: "Link" | "Video" | "Upload";
+    url: string;
+    mediaType?: string;
+    orderIndex?: number;
+}
+export interface AddResourceInput {
+    title: string;
+    type: "Link" | "Video" | "Upload";
+    url: string;
+    mediaType?: string;
+    orderIndex?: number;
+}
+export interface UploadUrlResponse {
+    /** Presigned URL for HTTP PUT upload */
+    putUrl: string;
+    /** Final S3 URL to use as the resource URL after upload */
+    url: string;
+    /** S3 object key */
+    key: string;
+    /** S3 bucket name */
+    bucket: string;
+}
+export interface UpdateTaskResourceInput {
+    /** Resource ID - include to update existing, omit to create new */
+    id?: string;
+    title: string;
+    type: "Link" | "Video" | "Upload";
+    url: string;
+    mediaType?: string;
+    orderIndex?: number;
+}
+export type BatchMissionAction = "add" | "update" | "delete";
+export interface BatchMissionAdd {
+    action: "add";
+    title: string;
+    description?: string;
+    category?: string;
+    subcategory?: string;
+    status?: string;
+    startAt?: string;
+    dueDate?: string;
+    linkId?: string;
+}
+export interface BatchMissionUpdate {
+    action: "update";
+    id: string;
+    title?: string;
+    description?: string;
+    category?: string;
+    subcategory?: string;
+    status?: string;
+    startAt?: string;
+    dueDate?: string;
+}
+export interface BatchMissionDelete {
+    action: "delete";
+    id: string;
+}
+export type BatchMissionOperation = BatchMissionAdd | BatchMissionUpdate | BatchMissionDelete;
+export interface BatchEditMissionsInput {
+    userId: string;
+    roadmapId: string;
+    missions: BatchMissionOperation[];
+}
+export interface BatchEditMissionsResult {
+    id: string;
+    action: BatchMissionAction;
+    attr?: string;
+}
+export interface BatchDeleteRestoreResult {
+    success: boolean;
+}
+export interface User {
+    userId: string;
+    firstName: string;
+    lastName: string;
+    email: string;
+    profileImageId?: string;
+}
+export interface UserRoleInfo {
+    roleId: string;
+    isPrimary: boolean;
+}
+export interface CurrentUserRoles {
+    userId: string;
+    roles: UserRoleInfo[];
+}
+/**
+ * Prefilled field with value and source information
+ */
+export interface PrefilledField<T> {
+    value: T | null;
+    source: string | null;
+}
+/**
+ * Student profile prefilled information
+ * Retrieved from various sources (Salesforce, Student Center, etc.)
+ */
+export interface StudentPrefilledInfo {
+    /** Current grade level (e.g., "Year 12", "Grade 11") */
+    currentGrade: PrefilledField<string>;
+    /** Current school name */
+    currentSchool: PrefilledField<string>;
+    /** Curriculum or programme (e.g., ["IB", "AP"]) */
+    curriculum: PrefilledField<string[]>;
+    /** Application cycle in format "YYYY/YYYY" (e.g., "2026/2027") */
+    applicationCycle: PrefilledField<string>;
+    /** Target country for university application */
+    targetCountry: PrefilledField<string>;
+    /** Admission goals (e.g., "Top 15 schools", "Ivy League") */
+    admissionGoals: PrefilledField<string>;
+    /** Intended majors/courses of study */
+    intendedMajors: PrefilledField<string>;
+}
+/**
+ * Full student profile data
+ */
+export interface StudentProfile {
+    userId: string;
+    firstName: string;
+    lastName: string;
+    email: string;
+    profileImageId?: string;
+    [key: string]: unknown;
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/users.d.ts

@@ -0,0 +1,21 @@
+import type { CrimsonClient } from "./client";
+import type { User } from "./types";
+export declare class UsersApi {
+    private client;
+    constructor(client: CrimsonClient);
+    /**
+     * Get users by their IDs
+     * Useful for fetching user names when displaying "assignedBy" information
+     *
+     * @param userIds - Array of user IDs to fetch
+     * @returns Array of user objects with basic info (userId, firstName, lastName, email, profileImageId)
+     */
+    getByIds(userIds: string[]): Promise<User[]>;
+    /**
+     * Get a single user by ID
+     *
+     * @param userId - The user ID to fetch
+     * @returns User object or undefined if not found
+     */
+    getById(userId: string): Promise<User | undefined>;
+}

package/dist/core/users.js

@@ -0,0 +1,46 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsersApi = void 0;
+class UsersApi {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get users by their IDs
+     * Useful for fetching user names when displaying "assignedBy" information
+     *
+     * @param userIds - Array of user IDs to fetch
+     * @returns Array of user objects with basic info (userId, firstName, lastName, email, profileImageId)
+     */
+    getByIds(userIds) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!userIds || userIds.length === 0) {
+                return [];
+            }
+            const ids = userIds.join(",");
+            return this.client.fetch(`/roadmap/users?ids=${encodeURIComponent(ids)}`);
+        });
+    }
+    /**
+     * Get a single user by ID
+     *
+     * @param userId - The user ID to fetch
+     * @returns User object or undefined if not found
+     */
+    getById(userId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const users = yield this.getByIds([userId]);
+            return users[0];
+        });
+    }
+}
+exports.UsersApi = UsersApi;

package/dist/iframe/auth-state.d.ts

@@ -0,0 +1,7 @@
+import type { ZoidProps, AuthState } from "./types";
+export declare function getToken(): string | null;
+export declare function getStudentId(): string | null;
+export declare function getUserId(): string | null;
+export declare function getAuthState(): AuthState;
+export declare function subscribeToAuthState(callback: () => void): () => void;
+export declare function persistStandaloneAuth(payload: ZoidProps): void;

package/dist/iframe/auth-state.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getToken = getToken;
+exports.getStudentId = getStudentId;
+exports.getUserId = getUserId;
+exports.getAuthState = getAuthState;
+exports.subscribeToAuthState = subscribeToAuthState;
+exports.persistStandaloneAuth = persistStandaloneAuth;
+const constants_1 = require("./constants");
+const readFromLocalStorage = (key) => {
+    if (typeof window === "undefined")
+        return null;
+    try {
+        return localStorage.getItem(key);
+    }
+    catch (_a) {
+        return null;
+    }
+};
+const writeToLocalStorage = (key, value) => {
+    if (typeof window === "undefined")
+        return;
+    localStorage.setItem(key, value);
+};
+const readFromXprops = (key) => {
+    if (typeof window === "undefined" || !window.xprops)
+        return undefined;
+    return window.xprops[key];
+};
+function getToken() {
+    const token = readFromXprops("token");
+    if (token) {
+        return token;
+    }
+    // URL 参数优先级高于 localStorage，检测到时覆盖
+    if (typeof window !== "undefined") {
+        const params = new URLSearchParams(window.location.search);
+        const fromQuery = params.get("token");
+        if (fromQuery) {
+            writeToLocalStorage(constants_1.STORAGE_KEYS.token, fromQuery);
+            return fromQuery;
+        }
+    }
+    const stored = readFromLocalStorage(constants_1.STORAGE_KEYS.token);
+    if (stored) {
+        return stored;
+    }
+    return null;
+}
+function getStudentId() {
+    const studentId = readFromXprops("studentId");
+    if (studentId) {
+        return studentId;
+    }
+    // URL 参数优先级高于 localStorage，检测到时覆盖
+    if (typeof window !== "undefined") {
+        const params = new URLSearchParams(window.location.search);
+        const fromQuery = params.get("studentId");
+        if (fromQuery) {
+            writeToLocalStorage(constants_1.STORAGE_KEYS.studentId, fromQuery);
+            return fromQuery;
+        }
+    }
+    const stored = readFromLocalStorage(constants_1.STORAGE_KEYS.studentId);
+    if (stored) {
+        return stored;
+    }
+    return null;
+}
+function getUserId() {
+    const userId = readFromXprops("userId");
+    if (userId) {
+        return userId;
+    }
+    return readFromLocalStorage(constants_1.STORAGE_KEYS.userId);
+}
+// Cache the auth state to avoid creating new objects on every call
+// This is required for useSyncExternalStore to work correctly
+let cachedAuthState = null;
+function getAuthState() {
+    const token = getToken();
+    const userId = getUserId();
+    const studentId = getStudentId();
+    const user = readFromXprops("user");
+    const ready = Boolean(token && studentId);
+    // Return cached state if values haven't changed
+    if (cachedAuthState &&
+        cachedAuthState.token === token &&
+        cachedAuthState.userId === userId &&
+        cachedAuthState.studentId === studentId &&
+        cachedAuthState.user === user &&
+        cachedAuthState.ready === ready) {
+        return cachedAuthState;
+    }
+    // Cache and return new state
+    cachedAuthState = {
+        token,
+        userId,
+        studentId,
+        user: user && typeof user === "object" ? user : undefined,
+        ready,
+    };
+    return cachedAuthState;
+}
+function subscribeToAuthState(callback) {
+    if (typeof window === "undefined") {
+        return () => undefined;
+    }
+    const handler = () => callback();
+    window.addEventListener(constants_1.XPROPS_READY_EVENT, handler);
+    window.addEventListener("storage", handler);
+    return () => {
+        window.removeEventListener(constants_1.XPROPS_READY_EVENT, handler);
+        window.removeEventListener("storage", handler);
+    };
+}
+function persistStandaloneAuth(payload) {
+    if (typeof window === "undefined")
+        return;
+    writeToLocalStorage(constants_1.STORAGE_KEYS.token, payload.token);
+    writeToLocalStorage(constants_1.STORAGE_KEYS.userId, payload.userId);
+    writeToLocalStorage(constants_1.STORAGE_KEYS.studentId, payload.studentId);
+    window.xprops = payload;
+    window.dispatchEvent(new CustomEvent(constants_1.XPROPS_READY_EVENT));
+}

package/dist/iframe/constants.d.ts

@@ -0,0 +1,8 @@
+export declare const XPROPS_READY_EVENT = "xprops-ready";
+export declare const STORAGE_KEYS: {
+    readonly token: "crimson_token";
+    readonly userId: "crimson_user_id";
+    readonly studentId: "crimson_student_id";
+};
+export declare function getDefaultAllowedOrigins(): string[];
+export declare const VIRTUAL_MISSION_ID = "00000000-0000-0000-0000-000000000001";

package/dist/iframe/constants.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIRTUAL_MISSION_ID = exports.STORAGE_KEYS = exports.XPROPS_READY_EVENT = void 0;
+exports.getDefaultAllowedOrigins = getDefaultAllowedOrigins;
+exports.XPROPS_READY_EVENT = "xprops-ready";
+exports.STORAGE_KEYS = {
+    token: "crimson_token",
+    userId: "crimson_user_id",
+    studentId: "crimson_student_id",
+};
+const DEFAULT_ORIGINS = [
+    "http://localhost:3000",
+    "http://localhost:3001",
+    "http://localhost:3002",
+    "https://staging.app.crimsoneducation.org",
+    "https://app.crimsoneducation.org",
+    "https://app-new-roadmap.staging.app.crimsoneducation.io",
+    "https://staging.collegewise.myflamingo.ai",
+    "https://collegewise.myflamingo.ai",
+];
+function getDefaultAllowedOrigins() {
+    var _a;
+    if (typeof process !== "undefined" &&
+        ((_a = process.env) === null || _a === void 0 ? void 0 : _a.NEXT_PUBLIC_ALLOWED_PARENTS)) {
+        return process.env.NEXT_PUBLIC_ALLOWED_PARENTS.split(",");
+    }
+    return DEFAULT_ORIGINS;
+}
+exports.VIRTUAL_MISSION_ID = "00000000-0000-0000-0000-000000000001";

package/dist/iframe/index.d.ts

@@ -0,0 +1,5 @@
+export { setupIframeListener } from "./listener";
+export type { CleanupFn } from "./listener";
+export { getToken, getUserId, getStudentId, getAuthState, subscribeToAuthState, persistStandaloneAuth, } from "./auth-state";
+export { XPROPS_READY_EVENT, STORAGE_KEYS, VIRTUAL_MISSION_ID, getDefaultAllowedOrigins, } from "./constants";
+export type { ZoidProps, AuthState } from "./types";

package/dist/iframe/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultAllowedOrigins = exports.VIRTUAL_MISSION_ID = exports.STORAGE_KEYS = exports.XPROPS_READY_EVENT = exports.persistStandaloneAuth = exports.subscribeToAuthState = exports.getAuthState = exports.getStudentId = exports.getUserId = exports.getToken = exports.setupIframeListener = void 0;
+var listener_1 = require("./listener");
+Object.defineProperty(exports, "setupIframeListener", { enumerable: true, get: function () { return listener_1.setupIframeListener; } });
+var auth_state_1 = require("./auth-state");
+Object.defineProperty(exports, "getToken", { enumerable: true, get: function () { return auth_state_1.getToken; } });
+Object.defineProperty(exports, "getUserId", { enumerable: true, get: function () { return auth_state_1.getUserId; } });
+Object.defineProperty(exports, "getStudentId", { enumerable: true, get: function () { return auth_state_1.getStudentId; } });
+Object.defineProperty(exports, "getAuthState", { enumerable: true, get: function () { return auth_state_1.getAuthState; } });
+Object.defineProperty(exports, "subscribeToAuthState", { enumerable: true, get: function () { return auth_state_1.subscribeToAuthState; } });
+Object.defineProperty(exports, "persistStandaloneAuth", { enumerable: true, get: function () { return auth_state_1.persistStandaloneAuth; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "XPROPS_READY_EVENT", { enumerable: true, get: function () { return constants_1.XPROPS_READY_EVENT; } });
+Object.defineProperty(exports, "STORAGE_KEYS", { enumerable: true, get: function () { return constants_1.STORAGE_KEYS; } });
+Object.defineProperty(exports, "VIRTUAL_MISSION_ID", { enumerable: true, get: function () { return constants_1.VIRTUAL_MISSION_ID; } });
+Object.defineProperty(exports, "getDefaultAllowedOrigins", { enumerable: true, get: function () { return constants_1.getDefaultAllowedOrigins; } });

package/dist/iframe/listener.d.ts

@@ -0,0 +1,2 @@
+export type CleanupFn = () => void;
+export declare function setupIframeListener(allowedOrigins?: string[]): CleanupFn;