@learncard/helpers 1.2.9 → 1.2.10

package/dist/helpers.d.ts

@@ -634,6 +634,67 @@ export type DeepPartial<T> = T extends Date ? T : T extends object ? {
 } : T;
 export declare const isNotUndefined: <T>(value: T | null | undefined) => value is T;
 export declare const filterUndefined: <T>(arr: (T | null | undefined)[]) => T[];
+/**
+ * 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 declare const checkAppInstallEligibility: (input: AppInstallCheckInput) => AppInstallCheckResult;
+/**
+ * Map age_rating strings to numeric minimum ages.
+ */
+export declare const AGE_RATING_TO_MIN_AGE: Record<string, number>;
+/**
+ * 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 declare const calculateAgeFromDob: (dob?: string | null) => number | null;
 /**
  * Determines whether or not a string is a valid hexadecimal string
  *

package/dist/helpers.esm.js

@@ -75,6 +75,7 @@ var require_types_cjs_development = __commonJS({
       AuthGrantQueryValidator: /* @__PURE__ */ __name(() => AuthGrantQueryValidator, "AuthGrantQueryValidator"),
       AuthGrantStatusValidator: /* @__PURE__ */ __name(() => AuthGrantStatusValidator, "AuthGrantStatusValidator"),
       AuthGrantValidator: /* @__PURE__ */ __name(() => AuthGrantValidator, "AuthGrantValidator"),
+      AuthSessionError: /* @__PURE__ */ __name(() => AuthSessionError, "AuthSessionError"),
       AutoBoostConfigValidator: /* @__PURE__ */ __name(() => AutoBoostConfigValidator, "AutoBoostConfigValidator"),
       BoostPermissionsQueryValidator: /* @__PURE__ */ __name(() => BoostPermissionsQueryValidator, "BoostPermissionsQueryValidator"),
       BoostPermissionsValidator: /* @__PURE__ */ __name(() => BoostPermissionsValidator, "BoostPermissionsValidator"),
@@ -82,6 +83,8 @@ var require_types_cjs_development = __commonJS({
       BoostRecipientValidator: /* @__PURE__ */ __name(() => BoostRecipientValidator, "BoostRecipientValidator"),
       BoostRecipientWithChildrenValidator: /* @__PURE__ */ __name(() => BoostRecipientWithChildrenValidator, "BoostRecipientWithChildrenValidator"),
       BoostValidator: /* @__PURE__ */ __name(() => BoostValidator, "BoostValidator"),
+      CheckCredentialEventValidator: /* @__PURE__ */ __name(() => CheckCredentialEventValidator, "CheckCredentialEventValidator"),
+      CheckIssuanceStatusEventValidator: /* @__PURE__ */ __name(() => CheckIssuanceStatusEventValidator, "CheckIssuanceStatusEventValidator"),
       ClaimHookQueryValidator: /* @__PURE__ */ __name(() => ClaimHookQueryValidator, "ClaimHookQueryValidator"),
       ClaimHookTypeValidator: /* @__PURE__ */ __name(() => ClaimHookTypeValidator, "ClaimHookTypeValidator"),
       ClaimHookValidator: /* @__PURE__ */ __name(() => ClaimHookValidator, "ClaimHookValidator"),
@@ -123,6 +126,7 @@ var require_types_cjs_development = __commonJS({
       CredentialActivityValidator: /* @__PURE__ */ __name(() => CredentialActivityValidator, "CredentialActivityValidator"),
       CredentialActivityWithDetailsValidator: /* @__PURE__ */ __name(() => CredentialActivityWithDetailsValidator, "CredentialActivityWithDetailsValidator"),
       CredentialInfoValidator: /* @__PURE__ */ __name(() => CredentialInfoValidator, "CredentialInfoValidator"),
+      CredentialNameRefValidator: /* @__PURE__ */ __name(() => CredentialNameRefValidator, "CredentialNameRefValidator"),
       CredentialRecordValidator: /* @__PURE__ */ __name(() => CredentialRecordValidator, "CredentialRecordValidator"),
       CredentialSchemaValidator: /* @__PURE__ */ __name(() => CredentialSchemaValidator, "CredentialSchemaValidator"),
       CredentialStatusValidator: /* @__PURE__ */ __name(() => CredentialStatusValidator, "CredentialStatusValidator"),
@@ -144,6 +148,7 @@ var require_types_cjs_development = __commonJS({
       GetFullSkillTreeResultValidator: /* @__PURE__ */ __name(() => GetFullSkillTreeResultValidator, "GetFullSkillTreeResultValidator"),
       GetSkillPathInputValidator: /* @__PURE__ */ __name(() => GetSkillPathInputValidator, "GetSkillPathInputValidator"),
       GetSkillPathResultValidator: /* @__PURE__ */ __name(() => GetSkillPathResultValidator, "GetSkillPathResultValidator"),
+      GetTemplateRecipientsEventValidator: /* @__PURE__ */ __name(() => GetTemplateRecipientsEventValidator, "GetTemplateRecipientsEventValidator"),
       IdentifierEntryValidator: /* @__PURE__ */ __name(() => IdentifierEntryValidator, "IdentifierEntryValidator"),
       IdentifierTypeValidator: /* @__PURE__ */ __name(() => IdentifierTypeValidator, "IdentifierTypeValidator"),
       IdentityObjectValidator: /* @__PURE__ */ __name(() => IdentityObjectValidator, "IdentityObjectValidator"),
@@ -14591,7 +14596,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       "PROFILE_PARENT_APPROVED",
       "APP_LISTING_SUBMITTED",
       "APP_LISTING_APPROVED",
-      "APP_LISTING_REJECTED"
+      "APP_LISTING_REJECTED",
+      "DEVICE_LINK_REQUEST"
     ]);
     var LCNNotificationMessageValidator = external_exports.object({
       title: external_exports.string().optional(),
@@ -14730,6 +14736,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       webhookUrl: external_exports.string().optional(),
       boostUri: external_exports.string().optional(),
       activityId: external_exports.string().optional(),
+      integrationId: external_exports.string().optional(),
       signingAuthority: external_exports.object({
         endpoint: external_exports.string().optional(),
         name: external_exports.string().optional()
@@ -14831,8 +14838,9 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       claimUrl: external_exports.string().url().optional(),
       recipientDid: external_exports.string().optional()
     });
+    var CredentialNameRefValidator = external_exports.object({ name: external_exports.string() }).passthrough();
     var ClaimInboxCredentialValidator = external_exports.object({
-      credential: VCValidator.or(VPValidator).or(UnsignedVCValidator).describe("The credential to issue."),
+      credential: VCValidator.or(VPValidator).or(UnsignedVCValidator).or(CredentialNameRefValidator).describe("The credential to issue, or a { name } reference to resolve a boost template."),
       configuration: external_exports.object({
         publishableKey: external_exports.string(),
         signingAuthorityName: external_exports.string().optional(),
@@ -15165,9 +15173,39 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     var SendCredentialEventValidator = external_exports.object({
       type: external_exports.literal("send-credential"),
       templateAlias: external_exports.string(),
-      templateData: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+      templateData: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
+      preventDuplicateClaim: external_exports.boolean().optional()
+    });
+    var CheckCredentialEventValidator = external_exports.object({
+      type: external_exports.literal("check-credential"),
+      templateAlias: external_exports.string().optional(),
+      boostUri: external_exports.string().optional()
+    }).refine((input) => Boolean(input.templateAlias) !== Boolean(input.boostUri), {
+      message: "Exactly one of templateAlias or boostUri is required"
+    });
+    var CheckIssuanceStatusEventValidator = external_exports.object({
+      type: external_exports.literal("check-issuance-status"),
+      templateAlias: external_exports.string().optional(),
+      boostUri: external_exports.string().optional(),
+      recipient: external_exports.string()
+    }).refine((input) => Boolean(input.templateAlias) !== Boolean(input.boostUri), {
+      message: "Exactly one of templateAlias or boostUri is required"
     });
-    var AppEventValidator = external_exports.discriminatedUnion("type", [SendCredentialEventValidator]);
+    var GetTemplateRecipientsEventValidator = external_exports.object({
+      type: external_exports.literal("get-template-recipients"),
+      templateAlias: external_exports.string().optional(),
+      boostUri: external_exports.string().optional(),
+      limit: external_exports.number().optional(),
+      cursor: external_exports.string().optional()
+    }).refine((input) => Boolean(input.templateAlias) !== Boolean(input.boostUri), {
+      message: "Exactly one of templateAlias or boostUri is required"
+    });
+    var AppEventValidator = external_exports.discriminatedUnion("type", [
+      SendCredentialEventValidator,
+      CheckCredentialEventValidator,
+      CheckIssuanceStatusEventValidator,
+      GetTemplateRecipientsEventValidator
+    ]);
     var AppEventInputValidator = external_exports.object({
       listingId: external_exports.string(),
       event: AppEventValidator
@@ -15230,6 +15268,19 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       failed: external_exports.number(),
       claimRate: external_exports.number()
     });
+    var AuthSessionError = class extends Error {
+      static {
+        __name(this, "AuthSessionError");
+      }
+      constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "AuthSessionError";
+      }
+      static {
+        __name2(this, "AuthSessionError");
+      }
+    };
   }
 });
 
@@ -16060,6 +16111,90 @@ var ImageWithLoadingStateValdator = z.object({
 var isNotUndefined = /* @__PURE__ */ __name((value) => Boolean(value), "isNotUndefined");
 var filterUndefined = /* @__PURE__ */ __name((arr) => arr.filter(isNotUndefined), "filterUndefined");
 
+// src/app-install/index.ts
+var checkAppInstallEligibility = /* @__PURE__ */ __name((input) => {
+  const {
+    isChildProfile,
+    userAge,
+    minAge,
+    ageRating,
+    hasContract,
+    hasGuardianApproval = false
+  } = input;
+  const ageRatingMinAge = getAgeRatingMinAge(ageRating);
+  const isHardBlocked = userAge !== null && minAge !== void 0 && minAge > 0 && userAge < minAge;
+  if (isHardBlocked) {
+    return {
+      action: "hard_blocked",
+      reason: `User does not meet the minimum age requirement of ${minAge}`
+    };
+  }
+  if (isChildProfile) {
+    const noAgeRating = ageRatingMinAge === 0;
+    const childAgeUnknown = userAge === null;
+    const childTooYoung = userAge !== null && userAge < ageRatingMinAge;
+    if (childAgeUnknown) {
+      if (hasGuardianApproval) {
+        return { action: "proceed" };
+      }
+      return {
+        action: "require_dob",
+        reason: "Child profile age is unknown and must be verified by guardian"
+      };
+    }
+    if (noAgeRating) {
+      if (hasGuardianApproval) {
+        return { action: "proceed" };
+      }
+      return {
+        action: "require_guardian_approval",
+        reason: "App has no age rating; guardian approval required for child profiles"
+      };
+    }
+    if (childTooYoung) {
+      if (hasGuardianApproval) {
+        return { action: "proceed" };
+      }
+      return {
+        action: "require_guardian_approval",
+        reason: `Child is under the age rating of ${ageRatingMinAge}+; guardian approval required`
+      };
+    }
+    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"
+      };
+    }
+  }
+  return { action: "proceed" };
+}, "checkAppInstallEligibility");
+var AGE_RATING_TO_MIN_AGE = {
+  "4+": 4,
+  "9+": 9,
+  "12+": 12,
+  "17+": 17
+};
+var getAgeRatingMinAge = /* @__PURE__ */ __name((ageRating) => {
+  if (!ageRating) return 0;
+  return AGE_RATING_TO_MIN_AGE[ageRating] ?? 0;
+}, "getAgeRatingMinAge");
+var calculateAgeFromDob = /* @__PURE__ */ __name((dob) => {
+  if (!dob) return null;
+  const birthDate = new Date(dob);
+  if (isNaN(birthDate.getTime())) return null;
+  const today = /* @__PURE__ */ 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;
+}, "calculateAgeFromDob");
+
 // src/index.ts
 var isHex = /* @__PURE__ */ __name((str) => /^[0-9a-f]+$/i.test(str), "isHex");
 var isEncrypted = /* @__PURE__ */ __name((item) => {
@@ -16109,13 +16244,16 @@ var isAppDidWeb = /* @__PURE__ */ __name((did) => {
   return LCN_APP_DID_WEB_REGEX.test(did);
 }, "isAppDidWeb");
 export {
+  AGE_RATING_TO_MIN_AGE,
   DEFAULT_RESOLUTIONS,
   ImageResizingValidator,
   ImageUploadingValidator,
   ImageWithLoadingStateValdator,
   RegExpTransformer,
+  calculateAgeFromDob,
   capitalizeFirstLetter,
   changeQuality4 as changeQuality,
+  checkAppInstallEligibility,
   curriedArraySlice,
   curriedInnerImmerOuterImmer,
   curriedInnerImmerOuterReact,