@academy-sdk/sdk 0.1.0 → 0.2.0

package/src/components/pages/index.ts

@@ -0,0 +1,13 @@
+export { MyLearningPage } from './MyLearningPage';
+export { CatalogCoursesPage } from './CatalogCoursesPage';
+export { CatalogBundlesPage } from './CatalogBundlesPage';
+export { CourseDetailPage } from './CourseDetailPage';
+export { BundleDetailPage } from './BundleDetailPage';
+export { CoursePlayerPage } from './CoursePlayerPage';
+export { MessagesPage } from './MessagesPage';
+export { ManualReviewPage } from './ManualReviewPage';
+export { ManualReviewDetailPage } from './ManualReviewDetailPage';
+export { LearnerSettingsPage } from './LearnerSettingsPage';
+export { PaymentSuccessPage } from './PaymentSuccessPage';
+export { PaymentCancelPage } from './PaymentCancelPage';
+export { CreatorProfilePage } from './CreatorProfilePage';

package/src/components/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/contracts/components.contract.ts

@@ -0,0 +1,89 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Props for a course card component (used in grids/lists)
+ */
+export interface CourseCardProps {
+  id: string;
+  title: string;
+  thumbnail?: string;
+  thumbnails?: string[];
+  totalLessons: number;
+  progress: number;
+  status?: 'in-progress' | 'completed';
+  isFree: boolean;
+  price?: number;
+  currency?: string;
+  description?: string;
+  showPrice?: boolean;
+  showProgress?: boolean;
+  category?: string;
+  duration?: string;
+  instructorName?: string;
+  instructorAvatar?: string;
+  originalPrice?: number;
+  isBundle?: boolean;
+  onClick?: () => void;
+}
+
+/**
+ * Props for a video player component
+ */
+export interface VideoPlayerProps {
+  videoUrl: string;
+  provider?: 'YOUTUBE' | 'VIMEO' | 'LOOM' | 'OTHERS';
+  startTime?: number;
+  onReady?: (player: any) => void;
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnd?: () => void;
+  onStateChange?: (event: any) => void;
+}
+
+/**
+ * Props for pagination component
+ */
+export interface PaginationComponentProps {
+  currentPage: number;
+  totalPages: number;
+  total: number;
+  pageSize: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+  onPageChange: (page: number) => void;
+  maxVisiblePages?: number;
+}
+
+/**
+ * Props for a page header component
+ */
+export interface PageHeaderProps {
+  title: string;
+  description?: string;
+  className?: string;
+}
+
+/**
+ * Props for search results view
+ */
+export interface SearchResultsViewProps {
+  results: any;
+  isSearching: boolean;
+  searchQuery: string;
+  onCourseClick: (courseId: string, enrollmentId?: string) => void;
+  onLessonClick: (courseId: string, lessonId: string) => void;
+}
+
+/**
+ * Props for the learner sidebar component override
+ */
+export interface LearnerSidebarComponentProps {
+  isOpen: boolean;
+  isCollapsed: boolean;
+  onClose: () => void;
+  onToggle: () => void;
+  currentPath: string;
+  onNavigate: (href: string) => void;
+  user: { name: string; email: string; avatar?: string } | null;
+  onLogout: () => void;
+}

package/src/contracts/index.ts

@@ -0,0 +1,4 @@
+export * from './layout.contract';
+export * from './pages.contract';
+export * from './components.contract';
+export * from './template.contract';

package/src/contracts/layout.contract.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+import type { User, Membership } from '../types';
+
+/**
+ * Props for the top-level learner layout wrapper.
+ * The template's layout receives these and renders navbar + sidebar + content.
+ */
+export interface LearnerLayoutProps {
+  children: ReactNode;
+  /** Current authenticated user */
+  user: User | null;
+  /** User's memberships */
+  memberships: Membership[];
+  /** Whether sidebar is open (mobile) */
+  sidebarOpen: boolean;
+  /** Whether sidebar is collapsed (desktop) */
+  sidebarCollapsed: boolean;
+  /** Toggle sidebar open/close */
+  onToggleSidebar: () => void;
+  /** Close sidebar (mobile) */
+  onCloseSidebar: () => void;
+  /** Logout handler */
+  onLogout: () => void;
+  /** Current pathname for active link highlighting */
+  pathname: string;
+}
+
+/**
+ * Navigation item for the sidebar
+ */
+export interface SidebarNavItem {
+  label: string;
+  href: string;
+  icon: string;
+  badge?: number;
+}

package/src/contracts/pages.contract.ts

@@ -0,0 +1,275 @@
+import type { ReactNode } from 'react';
+import type {
+  Course,
+  CoursePlayerCourse,
+  CoursePlayerModule,
+  Bundle,
+  LearnerBundle,
+  LearnerBundleCourse,
+  SearchCourse,
+  SearchResponse,
+  PaginationMeta,
+  User,
+  LearnerManualReviewSubmission,
+  LearnerManualReviewSummary,
+  LearnerManualReviewPagination,
+  LearnerManualReviewDetailResponse,
+  LearnerManualReviewStatus,
+  AICoachInfo,
+  Rating,
+  RatingSummary,
+  PaymentProvider,
+  Coupon,
+  ValidateCouponResponse,
+  LessonNote,
+  Bookmark,
+  FAQItem,
+  LessonResources,
+  TranscriptItem,
+} from '../types';
+
+// ─── My Learning Page ────────────────────────────────────────────
+export interface MyLearningPageProps {
+  user: User | null;
+  // Courses tab
+  courses: any[];
+  coursesMeta: PaginationMeta | null;
+  coursesLoading: boolean;
+  coursesPage: number;
+  onCoursesPageChange: (page: number) => void;
+  // Bundles tab
+  bundles: any[];
+  bundlesMeta: PaginationMeta | null;
+  bundlesLoading: boolean;
+  bundlesPage: number;
+  onBundlesPageChange: (page: number) => void;
+  // Search
+  searchQuery: string;
+  onSearchChange: (query: string) => void;
+  searchResults: SearchResponse | null;
+  isSearching: boolean;
+  // Filters
+  activeTab: 'courses' | 'bundles';
+  onTabChange: (tab: 'courses' | 'bundles') => void;
+  statusFilter: string;
+  onStatusFilterChange: (status: string) => void;
+  // Navigation
+  onCourseClick: (courseId: string, enrollmentId?: string) => void;
+  onBundleClick: (bundleId: string) => void;
+}
+
+// ─── Catalog Courses Page ────────────────────────────────────────
+export interface CatalogCoursesPageProps {
+  courses: Course[];
+  meta: PaginationMeta | null;
+  loading: boolean;
+  searchQuery: string;
+  page: number;
+  onSearchChange: (query: string) => void;
+  onPageChange: (page: number) => void;
+  onCourseClick: (courseId: string) => void;
+}
+
+// ─── Catalog Bundles Page ────────────────────────────────────────
+export interface CatalogBundlesPageProps {
+  bundles: Bundle[];
+  meta: PaginationMeta | null;
+  loading: boolean;
+  searchQuery: string;
+  page: number;
+  onSearchChange: (query: string) => void;
+  onPageChange: (page: number) => void;
+  onBundleClick: (bundleId: string) => void;
+}
+
+// ─── Course Detail Page ──────────────────────────────────────────
+export interface CourseDetailPageProps {
+  course: any | null;
+  isLoading: boolean;
+  notFound: boolean;
+  isEnrolled: boolean;
+  enrollmentId: string | null;
+  // Enrollment actions
+  onEnroll: () => Promise<void>;
+  onStartLearning: (enrollmentId: string) => void;
+  isProcessingEnrollment: boolean;
+  // Payment
+  paymentProviders: PaymentProvider[];
+  onCheckout: (providerId: string) => Promise<void>;
+  isProcessingCheckout: boolean;
+  // Coupons
+  couponCode: string;
+  onCouponCodeChange: (code: string) => void;
+  onApplyCoupon: () => Promise<void>;
+  appliedCoupon: Coupon | null;
+  couponError: string | null;
+  isApplyingCoupon: boolean;
+  discountedPrice: number | undefined;
+  // Tabs
+  activeTab: 'overview' | 'curriculum';
+  onTabChange: (tab: 'overview' | 'curriculum') => void;
+  // Related courses
+  relatedCourses: any[];
+  isRelatedLoading: boolean;
+  onRelatedCourseClick: (courseId: string) => void;
+  // Ratings
+  ratings?: Rating[];
+  ratingSummary?: RatingSummary;
+}
+
+// ─── Bundle Detail Page ──────────────────────────────────────────
+export interface BundleDetailPageProps {
+  bundle: LearnerBundle | null;
+  isLoading: boolean;
+  notFound: boolean;
+  isEnrolled: boolean;
+  // Enrollment
+  onEnroll: () => Promise<void>;
+  isProcessingEnrollment: boolean;
+  // Payment
+  paymentProviders: PaymentProvider[];
+  onCheckout: (providerId: string) => Promise<void>;
+  isProcessingCheckout: boolean;
+  // Coupons
+  couponCode: string;
+  onCouponCodeChange: (code: string) => void;
+  onApplyCoupon: () => Promise<void>;
+  appliedCoupon: Coupon | null;
+  couponError: string | null;
+  // Course list
+  onCourseClick: (courseId: string, enrollmentId?: string) => void;
+}
+
+// ─── Course Player Page ──────────────────────────────────────────
+export interface CoursePlayerPageProps {
+  // Course data
+  course: CoursePlayerCourse | null;
+  actualCourseId: string | null;
+  isLoading: boolean;
+  courseNotFound: boolean;
+  // Current lesson
+  currentLessonId: string;
+  currentModuleIndex: number;
+  currentLessonIndex: number;
+  // Module navigation
+  expandedModules: Set<string>;
+  onToggleModule: (moduleId: string) => void;
+  onSelectLesson: (lessonId: string) => void;
+  // Progress
+  completedCount: number;
+  totalCount: number;
+  isCompleted: boolean;
+  // Video
+  currentVideoTime: number;
+  isPlaying: boolean;
+  onVideoReady: (player: any) => void;
+  onVideoPlay: () => void;
+  onVideoPause: () => void;
+  onVideoEnd: () => void;
+  onVideoStateChange: (event: any) => void;
+  // Tabs
+  activeTab: string;
+  onTabChange: (tab: string) => void;
+  // Notes
+  notes: LessonNote[];
+  onCreateNote: (text: string, timestamp?: number) => Promise<void>;
+  onUpdateNote: (noteId: string, text: string) => Promise<void>;
+  onDeleteNote: (noteId: string) => Promise<void>;
+  // Bookmarks
+  bookmarks: Bookmark[];
+  onCreateBookmark: (second: number, label?: string) => Promise<void>;
+  onUpdateBookmark: (id: string, label: string) => Promise<void>;
+  onDeleteBookmark: (id: string) => Promise<void>;
+  // AI Coach
+  aiCoachAvailable: boolean;
+  aiCoachInfo: AICoachInfo | null;
+  // Certificate
+  certificateEnabled: boolean;
+  onDownloadCertificate: () => Promise<void>;
+  // Rating
+  showRatingModal: boolean;
+  onSubmitRating: (rating: number, review: string) => Promise<void>;
+  onCloseRatingModal: () => void;
+  // Slack
+  slackCommunityEnabled: boolean;
+  onJoinSlackChannel: () => Promise<void>;
+  // Mobile
+  isMobileSidebarOpen: boolean;
+  onToggleMobileSidebar: () => void;
+  // Get live video time (for notes/bookmarks)
+  getLiveCurrentTime: () => number;
+}
+
+// ─── Messages Page ───────────────────────────────────────────────
+export interface MessagesPageProps {
+  conversations: any[];
+  isLoadingConversations: boolean;
+  selectedConversation: any | null;
+  onSelectConversation: (conv: any) => void;
+  messages: any[];
+  isLoadingMessages: boolean;
+  isLoadingMore: boolean;
+  hasMoreMessages: boolean;
+  onLoadMoreMessages: () => void;
+  onSendMessage: (content: string) => Promise<void>;
+  isSending: boolean;
+  searchQuery: string;
+  onSearchChange: (query: string) => void;
+  onDeleteMessage: (messageId: string) => void;
+  showNewMessageDialog: boolean;
+  onNewMessageDialogChange: (show: boolean) => void;
+  onNewMessage: (courseId: string, message: string, conversationId: string, courseName?: string) => void;
+  notifications: any[];
+  unreadCount: number;
+  mobileView: 'list' | 'chat';
+  onMobileViewChange: (view: 'list' | 'chat') => void;
+  currentUserId: string;
+}
+
+// ─── Manual Review Page ──────────────────────────────────────────
+export interface ManualReviewPageProps {
+  submissions: LearnerManualReviewSubmission[];
+  summary: LearnerManualReviewSummary;
+  pagination: LearnerManualReviewPagination;
+  isLoading: boolean;
+  // Filters
+  filterStatus: LearnerManualReviewStatus | 'ALL';
+  onFilterStatusChange: (status: LearnerManualReviewStatus | 'ALL') => void;
+  searchQuery: string;
+  onSearchChange: (query: string) => void;
+  currentPage: number;
+  onPageChange: (page: number) => void;
+  // Navigation
+  onSubmissionClick: (submissionId: string) => void;
+}
+
+// ─── Manual Review Detail Page ───────────────────────────────────
+export interface ManualReviewDetailPageProps {
+  submission: LearnerManualReviewDetailResponse | null;
+  isLoading: boolean;
+  notFound: boolean;
+  onBack: () => void;
+}
+
+// ─── Learner Settings Page ───────────────────────────────────────
+export interface LearnerSettingsPageProps {
+  user: User | null;
+}
+
+// ─── Payment Result Pages ────────────────────────────────────────
+export interface PaymentSuccessPageProps {
+  onContinueLearning: () => void;
+}
+
+export interface PaymentCancelPageProps {
+  onRetry: () => void;
+  onGoBack: () => void;
+}
+
+// ─── Creator Profile Page ────────────────────────────────────────
+export interface CreatorProfilePageProps {
+  creator: any | null;
+  courses: Course[];
+  isLoading: boolean;
+  onCourseClick: (courseId: string) => void;
+}

package/src/contracts/template.contract.ts

@@ -0,0 +1,100 @@
+import type { ComponentType } from 'react';
+import type { LearnerLayoutProps } from './layout.contract';
+import type {
+  MyLearningPageProps,
+  CatalogCoursesPageProps,
+  CatalogBundlesPageProps,
+  CourseDetailPageProps,
+  BundleDetailPageProps,
+  CoursePlayerPageProps,
+  MessagesPageProps,
+  ManualReviewPageProps,
+  ManualReviewDetailPageProps,
+  LearnerSettingsPageProps,
+  PaymentSuccessPageProps,
+  PaymentCancelPageProps,
+  CreatorProfilePageProps,
+} from './pages.contract';
+import type {
+  CourseCardProps,
+  VideoPlayerProps,
+  PaginationComponentProps,
+  PageHeaderProps,
+  SearchResultsViewProps,
+  LearnerSidebarComponentProps,
+} from './components.contract';
+
+/**
+ * TemplateManifest defines the complete set of components a template must/can provide.
+ * 
+ * Required: LearnerLayout + all page components
+ * Optional: component overrides (will fallback to platform defaults if not provided)
+ */
+export interface TemplateManifest {
+  /** Unique template name (e.g., "@client/modern-template") */
+  name: string;
+  /** Template version (semver) */
+  version: string;
+
+  /** The root layout component wrapping all learner pages */
+  LearnerLayout: ComponentType<LearnerLayoutProps>;
+
+  /** Page components — one per learner route */
+  pages: {
+    MyLearningPage: ComponentType<Partial<MyLearningPageProps>>;
+    CatalogCoursesPage: ComponentType<Partial<CatalogCoursesPageProps>>;
+    CatalogBundlesPage: ComponentType<Partial<CatalogBundlesPageProps>>;
+    CourseDetailPage: ComponentType<Partial<CourseDetailPageProps>>;
+    BundleDetailPage: ComponentType<Partial<BundleDetailPageProps>>;
+    CoursePlayerPage: ComponentType<Partial<CoursePlayerPageProps>>;
+    MessagesPage: ComponentType<Partial<MessagesPageProps>>;
+    ManualReviewPage: ComponentType<Partial<ManualReviewPageProps>>;
+    ManualReviewDetailPage: ComponentType<Partial<ManualReviewDetailPageProps>>;
+    LearnerSettingsPage: ComponentType<Partial<LearnerSettingsPageProps>>;
+    PaymentSuccessPage: ComponentType<Partial<PaymentSuccessPageProps>>;
+    PaymentCancelPage: ComponentType<Partial<PaymentCancelPageProps>>;
+    CreatorProfilePage: ComponentType<Partial<CreatorProfilePageProps>>;
+  };
+
+  /** Optional component overrides — templates can provide custom implementations */
+  components?: {
+    CourseCard?: ComponentType<CourseCardProps>;
+    VideoPlayer?: ComponentType<VideoPlayerProps>;
+    Pagination?: ComponentType<PaginationComponentProps>;
+    PageHeader?: ComponentType<PageHeaderProps>;
+    SearchResultsView?: ComponentType<SearchResultsViewProps>;
+    LearnerSidebar?: ComponentType<LearnerSidebarComponentProps>;
+  };
+}
+
+/**
+ * Validates that a template manifest has all required fields.
+ * Throws an error if any required page is missing.
+ */
+export function validateTemplateManifest(manifest: TemplateManifest): void {
+  if (!manifest.name) throw new Error('Template manifest must have a name');
+  if (!manifest.version) throw new Error('Template manifest must have a version');
+  if (!manifest.LearnerLayout) throw new Error('Template must provide LearnerLayout');
+
+  const requiredPages = [
+    'MyLearningPage',
+    'CatalogCoursesPage',
+    'CatalogBundlesPage',
+    'CourseDetailPage',
+    'BundleDetailPage',
+    'CoursePlayerPage',
+    'MessagesPage',
+    'ManualReviewPage',
+    'ManualReviewDetailPage',
+    'LearnerSettingsPage',
+    'PaymentSuccessPage',
+    'PaymentCancelPage',
+    'CreatorProfilePage',
+  ] as const;
+
+  for (const page of requiredPages) {
+    if (!manifest.pages[page]) {
+      throw new Error(`Template must provide pages.${page}`);
+    }
+  }
+}

package/src/default-template.tsx

@@ -0,0 +1,52 @@
+import type { TemplateManifest } from './contracts';
+import { validateTemplateManifest } from './contracts';
+import manifest from './manifest.json';
+import { DefaultLayout } from './layouts/DefaultLayout';
+import {
+  MyLearningPage,
+  CatalogCoursesPage,
+  CatalogBundlesPage,
+  CourseDetailPage,
+  BundleDetailPage,
+  CoursePlayerPage,
+  MessagesPage,
+  ManualReviewPage,
+  ManualReviewDetailPage,
+  LearnerSettingsPage,
+  PaymentSuccessPage,
+  PaymentCancelPage,
+  CreatorProfilePage,
+} from './components/pages';
+import { CourseCard, Pagination, PageHeader } from './components/molecules';
+import { LearnerSidebar } from './components/organisms';
+
+const template: TemplateManifest = {
+  name: manifest.name,
+  version: manifest.version,
+  LearnerLayout: DefaultLayout,
+  pages: {
+    MyLearningPage,
+    CatalogCoursesPage,
+    CatalogBundlesPage,
+    CourseDetailPage,
+    BundleDetailPage,
+    CoursePlayerPage,
+    MessagesPage,
+    ManualReviewPage,
+    ManualReviewDetailPage,
+    LearnerSettingsPage,
+    PaymentSuccessPage,
+    PaymentCancelPage,
+    CreatorProfilePage,
+  },
+  components: {
+    CourseCard,
+    Pagination,
+    PageHeader,
+    LearnerSidebar,
+  },
+};
+
+validateTemplateManifest(template);
+
+export default template;

package/src/hooks/index.ts

@@ -0,0 +1,28 @@
+// Context & Provider
+export { SDKProvider, useSDK } from './sdk-context';
+export type { SDKHookImplementations, SDKProviderProps } from './sdk-context';
+
+// User & Auth
+export { useUser, useLogout } from './useUser';
+
+// Data hooks
+export { useMyCourses } from './useMyCourses';
+export { useMyBundles } from './useMyBundles';
+export { useCourseSearch } from './useCourseSearch';
+
+// Lesson features
+export { useLessonNotes, useCreateNote, useUpdateNote, useDeleteNote } from './useNotes';
+export { useLessonBookmarks, useCreateBookmark, useUpdateBookmark, useDeleteBookmark } from './useBookmarks';
+
+// AI Coach
+export { useAiCoachAvailability, useAiCoachChat, useAiCoachHistory } from './useAiCoach';
+
+// Notifications
+export { useNotifications } from './useNotifications';
+
+// Theme
+export { useTheme } from './useTheme';
+
+// Utilities
+export { useDebounce } from './useDebounce';
+export { useToast } from './useToast';