@academy-sdk/sdk 0.1.0 → 0.2.0

package/src/hooks/sdk-context.tsx

@@ -0,0 +1,152 @@
+'use client';
+
+import { createContext, useContext, type ReactNode } from 'react';
+import type { User, Membership } from '../types';
+
+/**
+ * SDK Hook implementations provided by the platform.
+ * Template developers don't interact with this directly — they use the individual hooks.
+ */
+export interface SDKHookImplementations {
+  // User & Auth
+  useUser: () => { user: User | null; isAuthenticated: boolean; memberships: Membership[] };
+  useLogout: () => { logout: () => void };
+
+  // My Learning
+  useMyCourses: (status?: string, page?: number, limit?: number) => {
+    courses: any[];
+    meta: any | null;
+    isLoading: boolean;
+  };
+  useMyBundles: (status?: string, page?: number, limit?: number, search?: string) => {
+    bundles: any[];
+    meta: any | null;
+    isLoading: boolean;
+  };
+
+  // Search
+  useCourseSearch: (query: string) => {
+    results: any | null;
+    isSearching: boolean;
+  };
+
+  // Notes
+  useLessonNotes: (activityId: string) => {
+    data: any[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+  };
+  useCreateNote: () => {
+    createNote: (payload: any) => Promise<any>;
+    isLoading: boolean;
+  };
+  useUpdateNote: () => {
+    updateNote: (noteId: string, payload: any) => Promise<any>;
+    isLoading: boolean;
+  };
+  useDeleteNote: () => {
+    deleteNote: (noteId: string) => Promise<boolean>;
+    isLoading: boolean;
+  };
+
+  // Bookmarks
+  useLessonBookmarks: (activityId: string) => {
+    data: any[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+  };
+  useCreateBookmark: () => {
+    createBookmark: (payload: any) => Promise<any>;
+    isLoading: boolean;
+  };
+  useUpdateBookmark: () => {
+    updateBookmark: (id: string, payload: any) => Promise<any>;
+    isLoading: boolean;
+  };
+  useDeleteBookmark: () => {
+    deleteBookmark: (id: string) => Promise<boolean>;
+    isLoading: boolean;
+  };
+
+  // AI Coach
+  useAiCoachAvailability: (courseId?: string | null) => {
+    loading: boolean;
+    active: boolean;
+    coach: any | null;
+    error: Error | null;
+  };
+  useAiCoachChat: (courseId: string | null | undefined) => {
+    messages: any[];
+    threadId: string | null;
+    isStreaming: boolean;
+    error: Error | null;
+    sendMessage: (text: string) => Promise<void>;
+    stopStreaming: () => void;
+  };
+  useAiCoachHistory: (courseId: string | null | undefined, enabled: boolean) => {
+    loading: boolean;
+    threadId: string | null;
+    messages: any[];
+    groupedHistory: any[];
+    hasMore: boolean;
+    loadMore: () => Promise<void>;
+  };
+
+  // Notifications
+  useNotifications: () => {
+    notifications: any[];
+    unreadCount: number;
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    hasMore: boolean;
+    loadMore: () => void;
+    refresh: () => void;
+    markConversationRead: (conversationId: string) => Promise<void>;
+  };
+
+  // Theme
+  useTheme: () => {
+    theme: string;
+    setTheme: (theme: string) => void;
+  };
+
+  // Debounce utility hook
+  useDebounce: <T>(value: T, delay: number) => T;
+
+  // Toast notifications
+  useToast: () => {
+    toast: (props: { title?: string; description?: string; variant?: 'default' | 'destructive' }) => void;
+  };
+}
+
+const SDKContext = createContext<SDKHookImplementations | null>(null);
+
+export interface SDKProviderProps {
+  implementations: SDKHookImplementations;
+  children: ReactNode;
+}
+
+/**
+ * SDKProvider wraps learner routes and provides hook implementations.
+ * Used by the platform internally — template developers don't need this.
+ */
+export function SDKProvider({ implementations, children }: SDKProviderProps) {
+  return <SDKContext.Provider value={implementations}>{children}</SDKContext.Provider>;
+}
+
+/**
+ * Internal hook to access SDK implementations.
+ * @internal
+ */
+export function useSDK(): SDKHookImplementations {
+  const ctx = useContext(SDKContext);
+  if (!ctx) {
+    throw new Error(
+      'useSDK must be used within an SDKProvider. ' +
+      'Make sure your learner routes are wrapped with <SDKProvider>.'
+    );
+  }
+  return ctx;
+}

package/src/hooks/useAiCoach.ts

@@ -0,0 +1,27 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Check if AI Coach is available for a course.
+ */
+export function useAiCoachAvailability(courseId?: string | null) {
+  const sdk = useSDK();
+  return sdk.useAiCoachAvailability(courseId);
+}
+
+/**
+ * Chat with the AI Coach.
+ */
+export function useAiCoachChat(courseId: string | null | undefined) {
+  const sdk = useSDK();
+  return sdk.useAiCoachChat(courseId);
+}
+
+/**
+ * Get AI Coach chat history.
+ */
+export function useAiCoachHistory(courseId: string | null | undefined, enabled: boolean) {
+  const sdk = useSDK();
+  return sdk.useAiCoachHistory(courseId, enabled);
+}

package/src/hooks/useBookmarks.ts

@@ -0,0 +1,35 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Fetch bookmarks for a lesson/activity.
+ */
+export function useLessonBookmarks(activityId: string) {
+  const sdk = useSDK();
+  return sdk.useLessonBookmarks(activityId);
+}
+
+/**
+ * Create a new bookmark.
+ */
+export function useCreateBookmark() {
+  const sdk = useSDK();
+  return sdk.useCreateBookmark();
+}
+
+/**
+ * Update an existing bookmark.
+ */
+export function useUpdateBookmark() {
+  const sdk = useSDK();
+  return sdk.useUpdateBookmark();
+}
+
+/**
+ * Delete a bookmark.
+ */
+export function useDeleteBookmark() {
+  const sdk = useSDK();
+  return sdk.useDeleteBookmark();
+}

package/src/hooks/useCourseSearch.ts

@@ -0,0 +1,18 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Search enrolled courses.
+ *
+ * @param query - Search query string
+ *
+ * @example
+ * ```tsx
+ * const { results, isSearching } = useCourseSearch(debouncedQuery);
+ * ```
+ */
+export function useCourseSearch(query: string) {
+  const sdk = useSDK();
+  return sdk.useCourseSearch(query);
+}

package/src/hooks/useDebounce.ts

@@ -0,0 +1,19 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Debounce a value.
+ *
+ * @param value - The value to debounce
+ * @param delay - Delay in milliseconds
+ *
+ * @example
+ * ```tsx
+ * const debouncedSearch = useDebounce(searchQuery, 500);
+ * ```
+ */
+export function useDebounce<T>(value: T, delay: number): T {
+  const sdk = useSDK();
+  return sdk.useDebounce(value, delay);
+}

package/src/hooks/useMyBundles.ts

@@ -0,0 +1,21 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Fetch the current user's enrolled bundles.
+ *
+ * @param status - Filter by status: 'IN_PROGRESS' | 'COMPLETED' | undefined (all)
+ * @param page - Page number (1-based)
+ * @param limit - Items per page (default: 12)
+ * @param search - Optional search query
+ *
+ * @example
+ * ```tsx
+ * const { bundles, meta, isLoading } = useMyBundles(undefined, 1, 12);
+ * ```
+ */
+export function useMyBundles(status?: string, page?: number, limit?: number, search?: string) {
+  const sdk = useSDK();
+  return sdk.useMyBundles(status, page, limit, search);
+}

package/src/hooks/useMyCourses.ts

@@ -0,0 +1,20 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Fetch the current user's enrolled courses.
+ *
+ * @param status - Filter by status: 'IN_PROGRESS' | 'COMPLETED' | undefined (all)
+ * @param page - Page number (1-based)
+ * @param limit - Items per page (default: 12)
+ *
+ * @example
+ * ```tsx
+ * const { courses, meta, isLoading } = useMyCourses('IN_PROGRESS', 1, 12);
+ * ```
+ */
+export function useMyCourses(status?: string, page?: number, limit?: number) {
+  const sdk = useSDK();
+  return sdk.useMyCourses(status, page, limit);
+}

package/src/hooks/useNotes.ts

@@ -0,0 +1,35 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Fetch notes for a lesson/activity.
+ */
+export function useLessonNotes(activityId: string) {
+  const sdk = useSDK();
+  return sdk.useLessonNotes(activityId);
+}
+
+/**
+ * Create a new note.
+ */
+export function useCreateNote() {
+  const sdk = useSDK();
+  return sdk.useCreateNote();
+}
+
+/**
+ * Update an existing note.
+ */
+export function useUpdateNote() {
+  const sdk = useSDK();
+  return sdk.useUpdateNote();
+}
+
+/**
+ * Delete a note.
+ */
+export function useDeleteNote() {
+  const sdk = useSDK();
+  return sdk.useDeleteNote();
+}

package/src/hooks/useNotifications.ts

@@ -0,0 +1,16 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Manage notifications (message notifications).
+ *
+ * @example
+ * ```tsx
+ * const { notifications, unreadCount, markConversationRead } = useNotifications();
+ * ```
+ */
+export function useNotifications() {
+  const sdk = useSDK();
+  return sdk.useNotifications();
+}

package/src/hooks/useTheme.ts

@@ -0,0 +1,17 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Access and change the current theme.
+ *
+ * @example
+ * ```tsx
+ * const { theme, setTheme } = useTheme();
+ * return <button onClick={() => setTheme('dark')}>Dark Mode</button>;
+ * ```
+ */
+export function useTheme() {
+  const sdk = useSDK();
+  return sdk.useTheme();
+}

package/src/hooks/useToast.ts

@@ -0,0 +1,17 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Show toast notifications.
+ *
+ * @example
+ * ```tsx
+ * const { toast } = useToast();
+ * toast({ title: 'Success', description: 'Course enrolled!' });
+ * ```
+ */
+export function useToast() {
+  const sdk = useSDK();
+  return sdk.useToast();
+}

package/src/hooks/useUser.ts

@@ -0,0 +1,33 @@
+'use client';
+
+import { useSDK } from './sdk-context';
+
+/**
+ * Get the current authenticated user.
+ *
+ * @example
+ * ```tsx
+ * const { user, isAuthenticated } = useUser();
+ * if (user) {
+ *   return <span>Hello, {user.name}</span>;
+ * }
+ * ```
+ */
+export function useUser() {
+  const sdk = useSDK();
+  return sdk.useUser();
+}
+
+/**
+ * Get the logout function.
+ *
+ * @example
+ * ```tsx
+ * const { logout } = useLogout();
+ * return <button onClick={logout}>Log out</button>;
+ * ```
+ */
+export function useLogout() {
+  const sdk = useSDK();
+  return sdk.useLogout();
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @academy/sdk
+ *
+ * SDK for building custom learner templates for the Academy platform.
+ *
+ * @example
+ * ```tsx
+ * import { useMyCourses, useUser } from '@academy/sdk';
+ * import type { MyLearningPageProps, TemplateManifest } from '@academy/sdk';
+ * ```
+ */
+
+// Types
+export * from './types';
+
+// Hooks
+export * from './hooks';
+
+// Contracts
+export * from './contracts';
+
+// Utilities
+export * from './utils';
+
+// Layouts
+export { DefaultLayout } from './layouts/DefaultLayout';
+
+// Components are available via sub-path imports:
+// import { Button, Card } from '@academy/sdk/components/atoms';
+// import { CourseCard, Pagination } from '@academy/sdk/components/molecules';
+// import { LearnerNavbar, LearnerSidebar } from '@academy/sdk/components/organisms';
+// import { MyLearningPage, CatalogCoursesPage } from '@academy/sdk/components/pages';
+// Or import all: import { Button, CourseCard } from '@academy/sdk/components';

package/src/layouts/DefaultLayout.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+import { useState, type ReactNode } from 'react';
+import { LearnerNavbar } from '../components/organisms/LearnerNavbar';
+import { LearnerSidebar } from '../components/organisms/LearnerSidebar';
+
+interface DefaultLayoutProps {
+  children: ReactNode;
+  currentPath?: string;
+  onNavigate?: (path: string) => void;
+}
+
+export function DefaultLayout({ children, currentPath = '/my-learning', onNavigate }: DefaultLayoutProps) {
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+
+  return (
+    <div className="min-h-screen bg-theme-bg-primary">
+      {/* Fixed Navbar */}
+      <div style={{ position: 'fixed', top: 'var(--preview-toolbar-h, 0px)', left: 0, right: 0, zIndex: 40 }}>
+        <LearnerNavbar
+          onMenuClick={() => {
+            if (typeof window !== 'undefined' && window.innerWidth >= 1024) {
+              setSidebarCollapsed(c => !c);
+            } else {
+              setSidebarOpen(o => !o);
+            }
+          }}
+        />
+      </div>
+
+      {/* Content below navbar (h-20 = 80px) + preview toolbar offset */}
+      <div style={{ paddingTop: 'calc(80px + var(--preview-toolbar-h, 0px))', display: 'flex', minHeight: '100vh' }}>
+        {/* Sidebar */}
+        <LearnerSidebar
+          currentPath={currentPath}
+          isCollapsed={sidebarCollapsed}
+          isOpen={sidebarOpen}
+          onClose={() => setSidebarOpen(false)}
+          onToggle={() => setSidebarCollapsed(c => !c)}
+          onNavigate={onNavigate ?? (() => {})}
+        />
+
+        {/* Main content */}
+        <main
+          style={{
+            flex: 1,
+            minWidth: 0,
+            transition: 'margin-left 0.3s',
+          }}
+          className="px-4 sm:px-6 lg:px-8 py-6"
+        >
+          {children}
+        </main>
+      </div>
+    </div>
+  );
+}

package/src/manifest.json

@@ -0,0 +1,5 @@
+{
+  "name": "@academy-sdk/sdk",
+  "version": "0.2.0",
+  "description": "SDK for building custom learner templates for the Academy platform"
+}

package/src/styles.css

@@ -0,0 +1,43 @@
+@import "tailwindcss";
+
+/* Tell Tailwind v4 where to scan for class names */
+@source "../src/**/*.{tsx,ts,js,jsx}";
+
+/* Mirror the host app's @theme mappings so custom Tailwind utilities work */
+@theme {
+  /* Background colors */
+  --color-theme-bg-primary: rgb(var(--bg-primary));
+  --color-theme-bg-secondary: rgb(var(--bg-secondary));
+  --color-theme-bg-tertiary: rgb(var(--bg-tertiary));
+
+  /* Text colors */
+  --color-theme-text-primary: rgb(var(--text-primary));
+  --color-theme-text-secondary: rgb(var(--text-secondary));
+  --color-theme-text-muted: rgb(var(--text-muted));
+
+  /* Border colors */
+  --color-theme-border-primary: rgb(var(--border-primary));
+
+  /* Accent colors */
+  --color-theme-accent-primary: rgb(var(--accent-primary));
+  --color-theme-accent-secondary: rgb(var(--accent-secondary));
+
+  /* Marketing success stats gradient */
+  --color-theme-success-gradient-from: rgb(var(--success-gradient-from));
+  --color-theme-success-gradient-to: rgb(var(--success-gradient-to));
+}
+
+/* Default (light) theme — fallback when host doesn't inject theme variables */
+:root {
+  --bg-primary: 249 250 251;
+  --bg-secondary: 255 255 255;
+  --bg-tertiary: 243 244 246;
+  --text-primary: 17 24 39;
+  --text-secondary: 75 85 99;
+  --text-muted: 156 163 175;
+  --border-primary: 229 231 235;
+  --accent-primary: 73 187 189;
+  --accent-secondary: 73 187 189;
+  --success-gradient-from: 19 108 181;
+  --success-gradient-to: 73 187 189;
+}

package/src/types/ai-coach.ts

@@ -0,0 +1,25 @@
+export type ChatRole = 'user' | 'assistant';
+
+export interface ChatMessage {
+  id: string;
+  role: ChatRole;
+  content: string;
+  createdAt: number;
+  isStreaming?: boolean;
+  sources?: unknown[];
+}
+
+export interface AICoachInfo {
+  id: string;
+  name: string;
+}
+
+export interface AICoachAvailability {
+  active: boolean;
+  coach: AICoachInfo | null;
+}
+
+export interface AICoachHistoryGroup {
+  date: string;
+  messages: ChatMessage[];
+}

package/src/types/bookmarks.ts

@@ -0,0 +1,20 @@
+export interface Bookmark {
+  id: string;
+  activityId: string;
+  userId: string;
+  second: number;
+  label?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateBookmarkPayload {
+  activityId: string;
+  second: number;
+  label?: string;
+}
+
+export interface UpdateBookmarkPayload {
+  second?: number;
+  label?: string;
+}