@sudobility/sudojo_lib 0.0.4

package/dist/hooks/useHint.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Hook for getting hints from the Sudoku solver
+ *
+ * Matches Kotlin HintInteractor behavior:
+ * - Stores all hint steps from the API response
+ * - Tracks current step index
+ * - next() advances to next step (if available)
+ * - previous() goes back to previous step
+ * - getHint() fetches new hints OR advances to next step if hints exist
+ */
+import { type ClientConfig, type SolverHintStep } from '@sudobility/sudojo_client';
+import type { NetworkClient } from '@sudobility/types';
+/** Board data returned when applying a hint */
+export interface HintBoardData {
+    /** 81-character user input string */
+    user: string;
+    /** Pencilmarks string (comma-separated) */
+    pencilmarks: string | null;
+    /** Whether auto-pencilmarks are enabled */
+    autoPencilmarks: boolean;
+}
+export interface UseHintOptions {
+    /** Network client for API calls */
+    networkClient: NetworkClient;
+    /** Solver client configuration */
+    config: ClientConfig;
+    /** Original puzzle string (81 chars) */
+    puzzle: string;
+    /** Current user input string (81 chars) */
+    userInput: string;
+    /** Current pencilmarks (comma-separated or empty) */
+    pencilmarks?: string;
+    /** Whether auto-pencilmarks were generated */
+    autoPencilmarks?: boolean;
+}
+export interface UseHintResult {
+    /** Current hint step being displayed */
+    hint: SolverHintStep | null;
+    /** All hint steps (for showing progress like "Step 1 of 3") */
+    hints: SolverHintStep[] | null;
+    /** Current step index (0-based) */
+    stepIndex: number;
+    /** Total number of steps */
+    totalSteps: number;
+    /** Whether a hint request is in progress */
+    isLoading: boolean;
+    /** Error message if hint request failed */
+    error: string | null;
+    /** Request hints or advance to next step */
+    getHint: () => Promise<void>;
+    /** Go to next hint step */
+    nextStep: () => void;
+    /** Go to previous hint step */
+    previousStep: () => void;
+    /** Clear all hints */
+    clearHint: () => void;
+    /** Apply the hint to the board - returns board data and clears hint */
+    applyHint: () => HintBoardData | null;
+    /** Whether there are more steps after current */
+    hasNextStep: boolean;
+    /** Whether there are steps before current */
+    hasPreviousStep: boolean;
+    /** Whether the hint can be applied (on last step) */
+    canApply: boolean;
+}
+/**
+ * Hook for getting hints from the solver API
+ *
+ * Matches Kotlin HintInteractor behavior:
+ * - First call to getHint() fetches hints from API
+ * - Subsequent calls advance to next step (if available)
+ * - Use nextStep()/previousStep() to navigate manually
+ * - clearHint() resets everything
+ *
+ * @param options - Puzzle state for hint generation
+ * @returns Hint state and controls
+ *
+ * @example
+ * ```tsx
+ * const { hint, isLoading, getHint, nextStep, clearHint, applyHint } = useHint({
+ *   networkClient,
+ *   config,
+ *   puzzle: originalPuzzle,
+ *   userInput: currentInput,
+ *   pencilmarks: currentPencilmarks,
+ * });
+ *
+ * // Get hint button
+ * <Button onClick={getHint} disabled={isLoading}>Get Hint</Button>
+ *
+ * // Display hint
+ * {hint && <HintDisplay step={hint} />}
+ *
+ * // Apply hint to board
+ * const handleApply = () => {
+ *   const boardData = applyHint();
+ *   if (boardData) {
+ *     setUserInput(boardData.user);
+ *     setPencilmarks(boardData.pencilmarks);
+ *   }
+ * };
+ * ```
+ */
+export declare function useHint({ networkClient, config, puzzle, userInput, pencilmarks, autoPencilmarks, }: UseHintOptions): UseHintResult;
+//# sourceMappingURL=useHint.d.ts.map

package/dist/hooks/useHint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHint.d.ts","sourceRoot":"","sources":["../../src/hooks/useHint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACL,KAAK,YAAY,EAIjB,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,2CAA2C;IAC3C,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,aAAa,EAAE,aAAa,CAAC;IAC7B,kCAAkC;IAClC,MAAM,EAAE,YAAY,CAAC;IACrB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,+DAA+D;IAC/D,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IAC/B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAC;IACnB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,sBAAsB;IACtB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,uEAAuE;IACvE,SAAS,EAAE,MAAM,aAAa,GAAG,IAAI,CAAC;IACtC,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,OAAO,CAAC,EACtB,aAAa,EACb,MAAM,EACN,MAAM,EACN,SAAS,EACT,WAAW,EACX,eAAuB,GACxB,EAAE,cAAc,GAAG,aAAa,CA2IhC"}

package/dist/hooks/useHint.js

@@ -0,0 +1,179 @@
+/**
+ * Hook for getting hints from the Sudoku solver
+ *
+ * Matches Kotlin HintInteractor behavior:
+ * - Stores all hint steps from the API response
+ * - Tracks current step index
+ * - next() advances to next step (if available)
+ * - previous() goes back to previous step
+ * - getHint() fetches new hints OR advances to next step if hints exist
+ */
+import { useCallback, useRef, useState } from 'react';
+import { createSudojoSolverClient, } from '@sudobility/sudojo_client';
+/**
+ * Hook for getting hints from the solver API
+ *
+ * Matches Kotlin HintInteractor behavior:
+ * - First call to getHint() fetches hints from API
+ * - Subsequent calls advance to next step (if available)
+ * - Use nextStep()/previousStep() to navigate manually
+ * - clearHint() resets everything
+ *
+ * @param options - Puzzle state for hint generation
+ * @returns Hint state and controls
+ *
+ * @example
+ * ```tsx
+ * const { hint, isLoading, getHint, nextStep, clearHint, applyHint } = useHint({
+ *   networkClient,
+ *   config,
+ *   puzzle: originalPuzzle,
+ *   userInput: currentInput,
+ *   pencilmarks: currentPencilmarks,
+ * });
+ *
+ * // Get hint button
+ * <Button onClick={getHint} disabled={isLoading}>Get Hint</Button>
+ *
+ * // Display hint
+ * {hint && <HintDisplay step={hint} />}
+ *
+ * // Apply hint to board
+ * const handleApply = () => {
+ *   const boardData = applyHint();
+ *   if (boardData) {
+ *     setUserInput(boardData.user);
+ *     setPencilmarks(boardData.pencilmarks);
+ *   }
+ * };
+ * ```
+ */
+export function useHint({ networkClient, config, puzzle, userInput, pencilmarks, autoPencilmarks = false, }) {
+    const [hints, setHints] = useState(null);
+    const [stepIndex, setStepIndex] = useState(0);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // Track puzzle state to detect when we need to re-fetch
+    const lastPuzzleStateRef = useRef('');
+    // Store board data from API response for applying hint
+    const boardDataRef = useRef(null);
+    // Compute current hint step
+    const hint = hints?.[stepIndex] ?? null;
+    const totalSteps = hints?.length ?? 0;
+    const hasNextStep = stepIndex < totalSteps - 1;
+    const hasPreviousStep = stepIndex > 0;
+    // Can apply when on last step and have board data
+    const canApply = hints !== null &&
+        stepIndex === totalSteps - 1 &&
+        boardDataRef.current !== null;
+    // Fetch hints from API
+    const fetchHints = useCallback(async () => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            const client = createSudojoSolverClient(networkClient, config);
+            const solveOptions = {
+                original: puzzle,
+                user: userInput,
+                autoPencilmarks,
+                ...(pencilmarks !== undefined && { pencilmarks }),
+            };
+            const response = await client.solve(solveOptions);
+            if (response.success && response.data?.hints?.length) {
+                setHints(response.data.hints);
+                setStepIndex(0);
+                // Store board data for applying hint later
+                boardDataRef.current = response.data.board ?? null;
+                // Track the puzzle state we fetched for
+                lastPuzzleStateRef.current = `${puzzle}|${userInput}|${pencilmarks ?? ''}`;
+            }
+            else if (response.error) {
+                setError(response.error);
+                setHints(null);
+                boardDataRef.current = null;
+            }
+            else {
+                setError('No hints available');
+                setHints(null);
+                boardDataRef.current = null;
+            }
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : 'Failed to get hint');
+            setHints(null);
+            boardDataRef.current = null;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [networkClient, config, puzzle, userInput, pencilmarks, autoPencilmarks]);
+    // Get hint: fetch if no hints or puzzle changed, otherwise advance
+    const getHint = useCallback(async () => {
+        const currentPuzzleState = `${puzzle}|${userInput}|${pencilmarks ?? ''}`;
+        if (hints === null || lastPuzzleStateRef.current !== currentPuzzleState) {
+            // No hints or puzzle state changed - fetch new hints
+            await fetchHints();
+        }
+        else if (hasNextStep) {
+            // Have hints and more steps - advance to next
+            setStepIndex(prev => prev + 1);
+        }
+        // If at last step and hints exist, do nothing (stay on last step)
+    }, [hints, hasNextStep, fetchHints, puzzle, userInput, pencilmarks]);
+    // Navigate to next step
+    const nextStep = useCallback(() => {
+        if (hasNextStep) {
+            setStepIndex(prev => prev + 1);
+        }
+    }, [hasNextStep]);
+    // Navigate to previous step
+    const previousStep = useCallback(() => {
+        if (hasPreviousStep) {
+            setStepIndex(prev => prev - 1);
+        }
+    }, [hasPreviousStep]);
+    // Clear all hints
+    const clearHint = useCallback(() => {
+        setHints(null);
+        setStepIndex(0);
+        setError(null);
+        lastPuzzleStateRef.current = '';
+        boardDataRef.current = null;
+    }, []);
+    // Apply the hint to the board - returns board data and clears hint
+    const applyHint = useCallback(() => {
+        const board = boardDataRef.current;
+        if (!board?.user) {
+            return null;
+        }
+        const result = {
+            user: board.user,
+            pencilmarks: board.pencilmarks?.pencilmarks ?? null,
+            autoPencilmarks: board.pencilmarks?.auto ?? false,
+        };
+        // Clear hints after applying (matches Kotlin: result = null)
+        setHints(null);
+        setStepIndex(0);
+        setError(null);
+        lastPuzzleStateRef.current = '';
+        boardDataRef.current = null;
+        return result;
+    }, []);
+    return {
+        hint,
+        hints,
+        stepIndex,
+        totalSteps,
+        isLoading,
+        error,
+        getHint,
+        nextStep,
+        previousStep,
+        clearHint,
+        applyHint,
+        hasNextStep,
+        hasPreviousStep,
+        canApply,
+    };
+}
+//# sourceMappingURL=useHint.js.map

package/dist/hooks/useHint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHint.js","sourceRoot":"","sources":["../../src/hooks/useHint.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useLearning.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Hook for fetching and managing learning materials for techniques
+ */
+import type { Learning } from '@sudobility/sudojo_types';
+import type { NetworkClient } from '@sudobility/types';
+import { type SudojoAuth, type SudojoConfig } from '@sudobility/sudojo_client';
+export interface UseLearningOptions {
+    /** Network client for API calls */
+    networkClient: NetworkClient;
+    /** Sudojo API configuration */
+    config: SudojoConfig;
+    /** Auth credentials (optional for public data) */
+    auth?: SudojoAuth;
+    /** Optional technique UUID to filter learning materials */
+    techniqueUuid?: string;
+    /** Optional language code to filter learning materials */
+    languageCode?: string;
+    /** Whether to enable the query */
+    enabled?: boolean;
+}
+export interface UseLearningResult {
+    /** All learning materials (optionally filtered) */
+    learningMaterials: Learning[];
+    /** Whether learning materials are loading */
+    isLoading: boolean;
+    /** Error if loading failed */
+    error: Error | null;
+    /** Refetch learning materials */
+    refetch: () => void;
+    /** Get learning material by UUID */
+    getLearningByUuid: (uuid: string) => Learning | undefined;
+    /** Learning materials sorted by index */
+    sortedLearning: Learning[];
+    /** Group learning materials by technique UUID */
+    learningByTechnique: Map<string, Learning[]>;
+    /** Group learning materials by language code */
+    learningByLanguage: Map<string, Learning[]>;
+}
+/**
+ * Hook for fetching and managing learning materials
+ *
+ * @param options - Hook options
+ * @returns Learning materials data and utilities
+ *
+ * @example
+ * ```tsx
+ * function LearningContent({ techniqueUuid }: { techniqueUuid: string }) {
+ *   const { learningMaterials, isLoading, sortedLearning } = useLearning({
+ *     networkClient,
+ *     config: { baseUrl: 'https://api.sudojo.com' },
+ *     techniqueUuid,
+ *     languageCode: 'en',
+ *   });
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       {sortedLearning.map(item => (
+ *         <div key={item.uuid}>
+ *           <p>{item.text}</p>
+ *           {item.image_url && <img src={item.image_url} alt="" />}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useLearning(options: UseLearningOptions): UseLearningResult;
+export interface UseLearningItemOptions {
+    /** Network client for API calls */
+    networkClient: NetworkClient;
+    /** Sudojo API configuration */
+    config: SudojoConfig;
+    /** Auth credentials (optional for public data) */
+    auth?: SudojoAuth;
+    /** Learning item UUID to fetch */
+    learningUuid: string;
+    /** Whether to enable the query */
+    enabled?: boolean;
+}
+export interface UseLearningItemResult {
+    /** The fetched learning item */
+    learningItem: Learning | null;
+    /** Whether learning item is loading */
+    isLoading: boolean;
+    /** Error if loading failed */
+    error: Error | null;
+    /** Refetch learning item */
+    refetch: () => void;
+}
+/**
+ * Hook for fetching a single learning item by UUID
+ *
+ * @param options - Hook options
+ * @returns Learning item data
+ */
+export declare function useLearningItem(options: UseLearningItemOptions): UseLearningItemResult;
+//# sourceMappingURL=useLearning.d.ts.map

package/dist/hooks/useLearning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLearning.d.ts","sourceRoot":"","sources":["../../src/hooks/useLearning.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EAGlB,MAAM,2BAA2B,CAAC;AAKnC,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,aAAa,EAAE,aAAa,CAAC;IAC7B,+BAA+B;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,kDAAkD;IAClD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,iBAAiB,EAAE,QAAQ,EAAE,CAAC;IAC9B,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,8BAA8B;IAC9B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,iCAAiC;IACjC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,oCAAoC;IACpC,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;IAC1D,yCAAyC;IACzC,cAAc,EAAE,QAAQ,EAAE,CAAC;IAC3B,iDAAiD;IACjD,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC7C,gDAAgD;IAChD,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAiF1E;AAED,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,aAAa,EAAE,aAAa,CAAC;IAC7B,+BAA+B;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,kDAAkD;IAClD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,YAAY,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC9B,uCAAuC;IACvC,SAAS,EAAE,OAAO,CAAC;IACnB,8BAA8B;IAC9B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAgCvB"}

package/dist/hooks/useLearning.js

@@ -0,0 +1,127 @@
+/**
+ * Hook for fetching and managing learning materials for techniques
+ */
+import { useMemo } from 'react';
+import { useSudojoLearning, useSudojoLearningItem, } from '@sudobility/sudojo_client';
+/** Default empty auth for public endpoints */
+const DEFAULT_AUTH = { accessToken: '' };
+/**
+ * Hook for fetching and managing learning materials
+ *
+ * @param options - Hook options
+ * @returns Learning materials data and utilities
+ *
+ * @example
+ * ```tsx
+ * function LearningContent({ techniqueUuid }: { techniqueUuid: string }) {
+ *   const { learningMaterials, isLoading, sortedLearning } = useLearning({
+ *     networkClient,
+ *     config: { baseUrl: 'https://api.sudojo.com' },
+ *     techniqueUuid,
+ *     languageCode: 'en',
+ *   });
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       {sortedLearning.map(item => (
+ *         <div key={item.uuid}>
+ *           <p>{item.text}</p>
+ *           {item.image_url && <img src={item.image_url} alt="" />}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useLearning(options) {
+    const { networkClient, config, auth = DEFAULT_AUTH, techniqueUuid, languageCode, enabled = true, } = options;
+    const queryParams = useMemo(() => {
+        // Only return params if at least one filter is provided
+        if (!techniqueUuid && !languageCode)
+            return undefined;
+        return {
+            technique_uuid: techniqueUuid ?? null,
+            language_code: languageCode ?? null,
+        };
+    }, [techniqueUuid, languageCode]);
+    const { data, isLoading, error, refetch } = useSudojoLearning(networkClient, config, auth, queryParams, { enabled });
+    const learningMaterials = useMemo(() => {
+        if (!data?.success || !data.data)
+            return [];
+        return data.data;
+    }, [data]);
+    const sortedLearning = useMemo(() => {
+        return [...learningMaterials].sort((a, b) => {
+            // First sort by technique UUID, then by index
+            if (a.technique_uuid !== b.technique_uuid) {
+                return (a.technique_uuid ?? '').localeCompare(b.technique_uuid ?? '');
+            }
+            return a.index - b.index;
+        });
+    }, [learningMaterials]);
+    const getLearningByUuid = useMemo(() => {
+        const learningMap = new Map(learningMaterials.map(l => [l.uuid, l]));
+        return (uuid) => learningMap.get(uuid);
+    }, [learningMaterials]);
+    const learningByTechnique = useMemo(() => {
+        const byTechnique = new Map();
+        for (const learning of sortedLearning) {
+            const key = learning.technique_uuid ?? '';
+            const existing = byTechnique.get(key) ?? [];
+            existing.push(learning);
+            byTechnique.set(key, existing);
+        }
+        return byTechnique;
+    }, [sortedLearning]);
+    const learningByLanguage = useMemo(() => {
+        const byLanguage = new Map();
+        for (const learning of sortedLearning) {
+            const key = learning.language_code;
+            const existing = byLanguage.get(key) ?? [];
+            existing.push(learning);
+            byLanguage.set(key, existing);
+        }
+        return byLanguage;
+    }, [sortedLearning]);
+    return {
+        learningMaterials,
+        isLoading,
+        error: error ?? null,
+        refetch: () => {
+            refetch();
+        },
+        getLearningByUuid,
+        sortedLearning,
+        learningByTechnique,
+        learningByLanguage,
+    };
+}
+/**
+ * Hook for fetching a single learning item by UUID
+ *
+ * @param options - Hook options
+ * @returns Learning item data
+ */
+export function useLearningItem(options) {
+    const { networkClient, config, auth = DEFAULT_AUTH, learningUuid, enabled = true, } = options;
+    const { data, isLoading, error, refetch } = useSudojoLearningItem(networkClient, config, auth, learningUuid, {
+        enabled: enabled && !!learningUuid,
+    });
+    const learningItem = useMemo(() => {
+        if (!data?.success || !data.data)
+            return null;
+        return data.data;
+    }, [data]);
+    return {
+        learningItem,
+        isLoading,
+        error: error ?? null,
+        refetch: () => {
+            refetch();
+        },
+    };
+}
+//# sourceMappingURL=useLearning.js.map

package/dist/hooks/useLearning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLearning.js","sourceRoot":"","sources":["../../src/hooks/useLearning.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAGhC,OAAO,EAGL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAEnC,8CAA8C;AAC9C,MAAM,YAAY,GAAe,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;AAoCrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,MAAM,EACJ,aAAa,EACb,MAAM,EACN,IAAI,GAAG,YAAY,EACnB,aAAa,EACb,YAAY,EACZ,OAAO,GAAG,IAAI,GACf,GAAG,OAAO,CAAC;IAEZ,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE;QAC/B,wDAAwD;QACxD,IAAI,CAAC,aAAa,IAAI,CAAC,YAAY;YAAE,OAAO,SAAS,CAAC;QACtD,OAAO;YACL,cAAc,EAAE,aAAa,IAAI,IAAI;YACrC,aAAa,EAAE,YAAY,IAAI,IAAI;SACpC,CAAC;IACJ,CAAC,EAAE,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC,CAAC;IAElC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,iBAAiB,CAC3D,aAAa,EACb,MAAM,EACN,IAAI,EACJ,WAAW,EACX,EAAE,OAAO,EAAE,CACZ,CAAC;IAEF,MAAM,iBAAiB,GAAG,OAAO,CAAC,GAAG,EAAE;QACrC,IAAI,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEX,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE;QAClC,OAAO,CAAC,GAAG,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAC1C,8CAA8C;YAC9C,IAAI,CAAC,CAAC,cAAc,KAAK,CAAC,CAAC,cAAc,EAAE,CAAC;gBAC1C,OAAO,CAAC,CAAC,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;YACxE,CAAC;YACD,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAExB,MAAM,iBAAiB,GAAG,OAAO,CAAC,GAAG,EAAE;QACrC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,OAAO,CAAC,IAAY,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAExB,MAAM,mBAAmB,GAAG,OAAO,CAAC,GAAG,EAAE;QACvC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAsB,CAAC;QAClD,KAAK,MAAM,QAAQ,IAAI,cAAc,EAAE,CAAC;YACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,cAAc,IAAI,EAAE,CAAC;YAC1C,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YAC5C,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACxB,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;IAErB,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,EAAE;QACtC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAsB,CAAC;QACjD,KAAK,MAAM,QAAQ,IAAI,cAAc,EAAE,CAAC;YACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,aAAa,CAAC;YACnC,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3C,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACxB,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAChC,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;IAErB,OAAO;QACL,iBAAiB;QACjB,SAAS;QACT,KAAK,EAAE,KAAK,IAAI,IAAI;QACpB,OAAO,EAAE,GAAG,EAAE;YACZ,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,iBAAiB;QACjB,cAAc;QACd,mBAAmB;QACnB,kBAAkB;KACnB,CAAC;AACJ,CAAC;AA0BD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA+B;IAE/B,MAAM,EACJ,aAAa,EACb,MAAM,EACN,IAAI,GAAG,YAAY,EACnB,YAAY,EACZ,OAAO,GAAG,IAAI,GACf,GAAG,OAAO,CAAC;IAEZ,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,qBAAqB,CAC/D,aAAa,EACb,MAAM,EACN,IAAI,EACJ,YAAY,EACZ;QACE,OAAO,EAAE,OAAO,IAAI,CAAC,CAAC,YAAY;KACnC,CACF,CAAC;IAEF,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,EAAE;QAChC,IAAI,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QAC9C,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEX,OAAO;QACL,YAAY;QACZ,SAAS;QACT,KAAK,EAAE,KAAK,IAAI,IAAI;QACpB,OAAO,EAAE,GAAG,EAAE;YACZ,OAAO,EAAE,CAAC;QACZ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/hooks/useLevelGame.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Hook for fetching and managing game board for a specific level
+ * Handles auth and subscription status with automatic refresh
+ */
+import type { Board } from '@sudobility/sudojo_types';
+import type { NetworkClient } from '@sudobility/types';
+import { type SudojoAuth, type SudojoConfig } from '@sudobility/sudojo_client';
+/** Game fetch status indicating what screen to show */
+export type GameFetchStatus = 'loading' | 'success' | 'auth_required' | 'subscription_required' | 'error';
+export interface UseLevelGameOptions {
+    /** Network client for API calls */
+    networkClient: NetworkClient;
+    /** Sudojo API configuration */
+    config: SudojoConfig;
+    /** Auth credentials with access token */
+    auth: SudojoAuth;
+    /** Level UUID to fetch game for */
+    levelId: string;
+    /** Whether subscription is currently active */
+    subscriptionActive?: boolean;
+    /** Whether to enable the query */
+    enabled?: boolean;
+}
+export interface UseLevelGameResult {
+    /** The game board data */
+    board: Board | null;
+    /** Current status of the game fetch */
+    status: GameFetchStatus;
+    /** Whether data is loading */
+    isLoading: boolean;
+    /** Error if fetch failed */
+    error: Error | null;
+    /** Refetch the game board */
+    refetch: () => void;
+    /** Fetch a new random board for this level */
+    nextPuzzle: () => void;
+}
+/**
+ * Hook for fetching a game board for a specific level
+ *
+ * Automatically refetches when auth token or subscription status changes.
+ * Returns status indicating whether auth or subscription is required.
+ *
+ * @param options - Hook options
+ * @returns Game board data and status
+ *
+ * @example
+ * ```tsx
+ * function LevelPlayPage({ levelId }: { levelId: string }) {
+ *   const { board, status, refetch, nextPuzzle } = useLevelGame({
+ *     networkClient,
+ *     config,
+ *     auth,
+ *     levelId,
+ *     subscriptionActive: subscription.isActive,
+ *   });
+ *
+ *   if (status === 'loading') return <Loading />;
+ *   if (status === 'auth_required') return <AuthRequired onLogin={openAuthModal} />;
+ *   if (status === 'subscription_required') return <SubscriptionPaywall onSuccess={refetch} />;
+ *   if (status === 'error') return <Error />;
+ *
+ *   return <SudokuGame puzzle={board.board} solution={board.solution} />;
+ * }
+ * ```
+ */
+export declare function useLevelGame(options: UseLevelGameOptions): UseLevelGameResult;
+//# sourceMappingURL=useLevelGame.d.ts.map

package/dist/hooks/useLevelGame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLevelGame.d.ts","sourceRoot":"","sources":["../../src/hooks/useLevelGame.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EAElB,MAAM,2BAA2B,CAAC;AAGnC,uDAAuD;AACvD,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,SAAS,GACT,eAAe,GACf,uBAAuB,GACvB,OAAO,CAAC;AAuDZ,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,aAAa,EAAE,aAAa,CAAC;IAC7B,+BAA+B;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,yCAAyC;IACzC,IAAI,EAAE,UAAU,CAAC;IACjB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,uCAAuC;IACvC,MAAM,EAAE,eAAe,CAAC;IACxB,8BAA8B;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,4BAA4B;IAC5B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAmF7E"}