@learncard/helpers 1.3.5 → 1.3.7

package/package.json

@@ -1,67 +1,69 @@
 {
-  "name": "@learncard/helpers",
-  "version": "1.3.5",
-  "description": "Shared helpers for LearnCard packages",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/helpers.esm.js",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/helpers.d.ts",
-        "default": "./dist/helpers.esm.js"
-      },
-      "require": {
-        "types": "./dist/helpers.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "author": "Learning Economy Foundation (www.learningeconomy.io)",
-  "license": "MIT",
-  "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/learn-card-helpers/README.md",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/learningeconomy/LearnCard"
-  },
-  "bugs": {
-    "url": "https://github.com/learningeconomy/LearnCard/issues"
-  },
-  "devDependencies": {
-    "@esbuild-plugins/node-resolve": "^0.1.4",
-    "@types/jest": "^27.5.0",
-    "@types/node": "^18.7.19",
-    "@types/react": "^18.0.0",
-    "aqu": "0.4.3",
-    "dts-bundle-generator": "^6.10.0",
-    "esbuild": "^0.27.1",
-    "esbuild-jest": "^0.5.0",
-    "jest": "^28.1.3",
-    "jest-environment-jsdom": "^28.1.3",
-    "shx": "^0.3.4",
-    "ts-jest": "^28.0.5"
-  },
-  "types": "./dist/helpers.d.ts",
-  "dependencies": {
-    "@noble/hashes": "^1.8.0",
-    "@sd-jwt/decode": "^0.19.0",
-    "@trpc/server": "11.7.1",
-    "immer": "^10.0.3",
-    "use-immer": "^0.9.0",
-    "zod": "^3.23.8",
-    "@learncard/types": "5.17.3"
-  },
-  "sideEffects": false,
-  "scripts": {
-    "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && dts-bundle-generator src/index.ts -o dist/helpers.d.ts --no-check && shx cp ./dist/helpers.d.ts ./dist/helpers.d.cts",
-    "start": "aqu watch",
-    "lint": "aqu lint",
-    "lint:fix": "aqu lint --fix",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
-  }
-}
+    "name": "@learncard/helpers",
+    "version": "1.3.7",
+    "description": "Shared helpers for LearnCard packages",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/helpers.esm.js",
+    "exports": {
+        ".": {
+            "development": "./src/index.ts",
+            "import": {
+                "types": "./dist/helpers.d.ts",
+                "default": "./dist/helpers.esm.js"
+            },
+            "require": {
+                "types": "./dist/helpers.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "files": [
+        "dist",
+        "src"
+    ],
+    "scripts": {
+        "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && dts-bundle-generator src/index.ts -o dist/helpers.d.ts --no-check && shx cp ./dist/helpers.d.ts ./dist/helpers.d.cts",
+        "start": "aqu watch",
+        "lint": "aqu lint",
+        "lint:fix": "aqu lint --fix",
+        "test": "jest",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
+    },
+    "author": "Learning Economy Foundation (www.learningeconomy.io)",
+    "license": "MIT",
+    "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/learn-card-helpers/README.md",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/learningeconomy/LearnCard"
+    },
+    "bugs": {
+        "url": "https://github.com/learningeconomy/LearnCard/issues"
+    },
+    "devDependencies": {
+        "@esbuild-plugins/node-resolve": "^0.1.4",
+        "@types/jest": "^27.5.0",
+        "@types/node": "^18.7.19",
+        "@types/react": "^18.0.0",
+        "aqu": "0.4.3",
+        "dts-bundle-generator": "^6.10.0",
+        "esbuild": "^0.27.1",
+        "esbuild-jest": "^0.5.0",
+        "jest": "^28.1.3",
+        "jest-environment-jsdom": "^28.1.3",
+        "shx": "^0.3.4",
+        "ts-jest": "^28.0.5"
+    },
+    "types": "./dist/helpers.d.ts",
+    "dependencies": {
+        "@noble/hashes": "^1.8.0",
+        "@sd-jwt/decode": "^0.19.0",
+        "@learncard/types": "workspace:*",
+        "@trpc/server": "11.7.1",
+        "immer": "^10.0.3",
+        "use-immer": "^0.9.0",
+        "zod": "4.1.13"
+    },
+    "sideEffects": false
+}

package/src/Utilities.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+
+// Note: SetState is exported from ./state.ts to avoid duplicate exports
+
+export const ImageResizingValidator = z.object({ type: z.literal('resizing') });
+export type ImageResizing = z.infer<typeof ImageResizingValidator>;
+
+export const ImageUploadingValidator = z.object({
+    type: z.literal('uploading'),
+    progress: z.number().optional(),
+});
+export type ImageUploading = z.infer<typeof ImageUploadingValidator>;
+
+export const ImageWithLoadingStateValdator = z.object({
+    image: z.string(),
+    loading: z.union([ImageResizingValidator, ImageUploadingValidator]).optional(),
+});
+export type ImageWithLoadingState = z.infer<typeof ImageWithLoadingStateValdator>;
+
+export type FilestackImage = {
+    filename: string;
+    handle: string;
+    mimetype: string;
+    originalFile: {
+        name: string;
+        size: number;
+        type: string;
+    };
+    originalPath: string;
+    size: number;
+    source: string;
+    status: string;
+    uploadId: string;
+    url: string;
+};
+
+export type Simplify<T> = {
+    [KeyType in keyof T]: T[KeyType];
+};
+
+export type Maybify<T> = Simplify<{
+    [P in keyof T]?: Maybify<T[P]> | null;
+}>;
+
+/** If Maybify gives you an exceeds maximum length error, try this one!  */
+export type PerformantMaybify<T> = {
+    [P in keyof T]?: PerformantMaybify<T[P]> | null;
+};
+
+export type DeepValues<ObjectType extends object> = {
+    [Key in keyof ObjectType & (string | number)]: ObjectType[Key] extends object
+        ? DeepValues<ObjectType[Key]>
+        : ObjectType[Key];
+}[keyof ObjectType & (string | number)];
+
+export interface Nothing {}
+export type Other<T> = T & Nothing;
+
+export type SuggestString<Literals extends string> = Literals | Other<string>;
+
+export type DeepPartial<T> = T extends Date
+    ? T
+    : T extends object
+    ? {
+          [P in keyof T]?: DeepPartial<T[P]>;
+      }
+    : T;
+
+export const isNotUndefined = <T>(value: T | null | undefined): value is T => Boolean(value);
+
+export const filterUndefined = <T>(arr: (T | null | undefined)[]) => arr.filter(isNotUndefined);

package/src/app-install/index.ts

@@ -0,0 +1,168 @@
+/**
+ * App installation age restriction logic shared between frontend and backend.
+ *
+ * This helper evaluates whether a user can install an app based on:
+ * - Hard age blocks (min_age) - always blocks, even with guardian approval
+ * - Soft age restrictions (age_rating) - can be approved by guardian for child profiles
+ * - Contract requirements - require guardian approval for child profiles
+ */
+
+export type AppInstallCheckResult =
+    | { action: 'proceed' }
+    | { action: 'hard_blocked'; reason: string }
+    | { action: 'require_dob'; reason: string }
+    | { action: 'require_guardian_approval'; reason: string };
+
+export type AppInstallCheckInput = {
+    /** Whether the user is a child profile (managed account) */
+    isChildProfile: boolean;
+    /** User's age calculated from DOB, null if DOB is unknown */
+    userAge: number | null;
+    /** Hard minimum age requirement (blocks completely, no guardian override) */
+    minAge?: number;
+    /** Soft age rating string (e.g., '4+', '9+', '12+', '17+') */
+    ageRating?: string;
+    /** Whether the app has an associated consent contract */
+    hasContract: boolean;
+    /** Whether guardian approval has already been obtained (for backend validation) */
+    hasGuardianApproval?: boolean;
+};
+
+/**
+ * Evaluates whether a user can install an app based on age restrictions and profile type.
+ *
+ * Cases:
+ * 1. Hard block: min_age violation (blocks completely, cannot be overridden)
+ * 2. Child profile scenarios:
+ *    2a. Child age unknown → require DOB entry (with guardian approval)
+ *    2b. No age rating specified → require guardian approval
+ *    2c. Child too young for age rating → require guardian approval
+ *    2d. App has a contract → require guardian approval
+ *    2e. Child old enough, no contract → proceed without guardian
+ * 3. Adult user old enough → proceed
+ *
+ * @param input - The check parameters
+ * @returns The action to take and reason if blocked/requires approval
+ */
+export const checkAppInstallEligibility = (input: AppInstallCheckInput): AppInstallCheckResult => {
+    const {
+        isChildProfile,
+        userAge,
+        minAge,
+        ageRating,
+        hasContract,
+        hasGuardianApproval = false,
+    } = input;
+
+    const ageRatingMinAge = getAgeRatingMinAge(ageRating);
+
+    // Case 1: Hard block - min_age violation (block completely)
+    // Only applies when userAge is known
+    const isHardBlocked =
+        userAge !== null && minAge !== undefined && minAge > 0 && userAge < minAge;
+
+    if (isHardBlocked) {
+        return {
+            action: 'hard_blocked',
+            reason: `User does not meet the minimum age requirement of ${minAge}`,
+        };
+    }
+
+    // Case 2: Child profile - check age restrictions
+    if (isChildProfile) {
+        const noAgeRating = ageRatingMinAge === 0;
+        const childAgeUnknown = userAge === null;
+        const childTooYoung = userAge !== null && userAge < ageRatingMinAge;
+
+        // Case 2a: Child age unknown - require guardian to verify age via DOB entry
+        // If guardian has already approved, allow proceed (DOB may not be saved yet)
+        if (childAgeUnknown) {
+            if (hasGuardianApproval) {
+                return { action: 'proceed' };
+            }
+            return {
+                action: 'require_dob',
+                reason: 'Child profile age is unknown and must be verified by guardian',
+            };
+        }
+
+        // Case 2b: No age rating specified - require guardian approval
+        if (noAgeRating) {
+            if (hasGuardianApproval) {
+                return { action: 'proceed' };
+            }
+            return {
+                action: 'require_guardian_approval',
+                reason: 'App has no age rating; guardian approval required for child profiles',
+            };
+        }
+
+        // Case 2c: Child too young for age rating - require guardian approval
+        if (childTooYoung) {
+            if (hasGuardianApproval) {
+                return { action: 'proceed' };
+            }
+            return {
+                action: 'require_guardian_approval',
+                reason: `Child is under the age rating of ${ageRatingMinAge}+; guardian approval required`,
+            };
+        }
+
+        // Case 2d: App with a contract - require guardian approval
+        if (hasContract) {
+            if (hasGuardianApproval) {
+                return { action: 'proceed' };
+            }
+            return {
+                action: 'require_guardian_approval',
+                reason: 'App requires consent to a contract; guardian approval required for child profiles',
+            };
+        }
+
+        // Case 2e: Child old enough, no contract - proceed directly without guardian approval
+    }
+
+    // Case 3: User is old enough (or adult) - proceed directly
+    return { action: 'proceed' };
+};
+
+/**
+ * Map age_rating strings to numeric minimum ages.
+ */
+export const AGE_RATING_TO_MIN_AGE: Record<string, number> = {
+    '4+': 4,
+    '9+': 9,
+    '12+': 12,
+    '17+': 17,
+};
+
+/**
+ * Convert an age_rating string to a numeric minimum age.
+ * Returns 0 if no rating is specified or the rating is unknown.
+ */
+const getAgeRatingMinAge = (ageRating?: string): number => {
+    if (!ageRating) return 0;
+    return AGE_RATING_TO_MIN_AGE[ageRating] ?? 0;
+};
+
+/**
+ * Calculate age in years from a date of birth string.
+ * @param dob - Date of birth as ISO string or parseable date string
+ * @returns Age in years, or null if the date is invalid
+ */
+export const calculateAgeFromDob = (dob?: string | null): number | null => {
+    if (!dob) return null;
+
+    const birthDate = new Date(dob);
+    if (isNaN(birthDate.getTime())) return null;
+
+    const today = new Date();
+    let age = today.getFullYear() - birthDate.getFullYear();
+    const monthDiff = today.getMonth() - birthDate.getMonth();
+
+    if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birthDate.getDate())) {
+        age--;
+    }
+
+    return age;
+};

package/src/arrays/index.ts

@@ -0,0 +1,20 @@
+/** Quantizes a number to the closest number in an array of numbers */
+export const quantizeValue = (value: number, array: number[]) => {
+    const foundIndex = array.findIndex((number) => number === value);
+
+    if (foundIndex > -1) return array[foundIndex];
+
+    const closestIndex = array.reduce(
+        (closest, current, index) => {
+            const currentDistance = Math.abs(current - value);
+
+            if (currentDistance <= closest.distance)
+                return { index, distance: currentDistance };
+
+            return closest;
+        },
+        { index: 0, distance: Infinity },
+    ).index;
+
+    return array[closestIndex];
+};

package/src/bitstring-status-list/index.ts

@@ -0,0 +1,69 @@
+import type { BitstringStatusListEntry, BitstringStatusPurpose } from '@learncard/types';
+
+export const getCredentialStatusArray = (credential: unknown): Record<string, unknown>[] => {
+    if (!credential || typeof credential !== 'object' || Array.isArray(credential)) return [];
+
+    const status = (credential as { credentialStatus?: unknown }).credentialStatus;
+    if (!status) return [];
+
+    return Array.isArray(status)
+        ? (status as Record<string, unknown>[])
+        : [status as Record<string, unknown>];
+};
+
+export const isBitstringStatusListEntry = (status: unknown): status is BitstringStatusListEntry => {
+    if (!status || typeof status !== 'object') return false;
+
+    const record = status as Record<string, unknown>;
+
+    return (
+        record.type === 'BitstringStatusListEntry' &&
+        (record.statusPurpose === 'revocation' || record.statusPurpose === 'suspension') &&
+        typeof record.statusListIndex === 'string' &&
+        typeof record.statusListCredential === 'string'
+    );
+};
+
+export const getBitstringStatusListEntries = (credential: unknown): BitstringStatusListEntry[] => {
+    if (!credential || typeof credential !== 'object' || Array.isArray(credential)) return [];
+
+    const record = credential as Record<string, unknown>;
+    const statuses = getCredentialStatusArray(record);
+
+    return [
+        ...statuses.filter(isBitstringStatusListEntry),
+        ...getBitstringStatusListEntries(record.boostCredential),
+    ];
+};
+
+export const getBitstringStatusListEntryForPurpose = (
+    credential: unknown,
+    statusPurpose: BitstringStatusPurpose
+): BitstringStatusListEntry | undefined =>
+    getBitstringStatusListEntries(credential).find(entry => entry.statusPurpose === statusPurpose);
+
+export const getBitstringStatusListBit = (bitstring: Uint8Array, index: number): boolean => {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error('Bitstring status list index is out of range');
+    }
+
+    const byte = bitstring[Math.floor(index / 8)] ?? 0;
+
+    return (byte & (1 << index % 8)) !== 0;
+};
+
+export const setBitstringStatusListBit = (
+    bitstring: Uint8Array,
+    index: number,
+    value: boolean
+): void => {
+    if (!Number.isInteger(index) || index < 0 || index >= bitstring.length * 8) {
+        throw new Error('Bitstring status list index is out of range');
+    }
+
+    const byteIndex = Math.floor(index / 8);
+    const mask = 1 << index % 8;
+    const current = bitstring[byteIndex] ?? 0;
+
+    bitstring[byteIndex] = value ? current | mask : current & ~mask;
+};