@learncard/helpers 1.7.3 → 1.8.0

package/dist/index.d.cts

@@ -16,6 +16,17 @@ export declare const RegExpTransformer: DataTransformer;
  * Determines if a credential uses VC 2.0 format by checking the context array
  */
 export declare const isVC2Format: (credential: unknown) => boolean;
+/**
+ * The marker field on the placeholder credential JSON of a "display-only anchor"
+ * Boost (one created by a managed/signed-only send that had no explicit credential).
+ * `'display' in boost` is NOT a safe way to detect this: ordinary Boosts commonly have
+ * their own top-level `display` object too (e.g. the LearnCard app's appearance fields —
+ * backgroundImage, backgroundColor, displayType), so that check produces false
+ * positives on real credentials.
+ */
+export declare const DISPLAY_ONLY_ANCHOR_MARKER: "displayOnlyAnchor";
+/** Detects a display-only anchor via its dedicated marker (see `DISPLAY_ONLY_ANCHOR_MARKER`). */
+export declare const isDisplayOnlyAnchorTemplate: (credential: unknown) => boolean;
 /** Unwraps a boost credential from a CertifiedBoostCredential, if it is one */
 export declare const unwrapBoostCredential: (vc?: VC | UnsignedVC) => any;
 export * from './images';
@@ -42,5 +53,7 @@ export * from './credential-format';
  */
 export declare const isAppDidWeb: (did?: string) => boolean;
 export * from './share-content-canonical';
+export * from './consent-flow-contract-updates';
 export * from './credential-materialization';
+export * from './age-policy';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -16,6 +16,17 @@ export declare const RegExpTransformer: DataTransformer;
  * Determines if a credential uses VC 2.0 format by checking the context array
  */
 export declare const isVC2Format: (credential: unknown) => boolean;
+/**
+ * The marker field on the placeholder credential JSON of a "display-only anchor"
+ * Boost (one created by a managed/signed-only send that had no explicit credential).
+ * `'display' in boost` is NOT a safe way to detect this: ordinary Boosts commonly have
+ * their own top-level `display` object too (e.g. the LearnCard app's appearance fields —
+ * backgroundImage, backgroundColor, displayType), so that check produces false
+ * positives on real credentials.
+ */
+export declare const DISPLAY_ONLY_ANCHOR_MARKER: "displayOnlyAnchor";
+/** Detects a display-only anchor via its dedicated marker (see `DISPLAY_ONLY_ANCHOR_MARKER`). */
+export declare const isDisplayOnlyAnchorTemplate: (credential: unknown) => boolean;
 /** Unwraps a boost credential from a CertifiedBoostCredential, if it is one */
 export declare const unwrapBoostCredential: (vc?: VC | UnsignedVC) => any;
 export * from './images';
@@ -42,5 +53,7 @@ export * from './credential-format';
  */
 export declare const isAppDidWeb: (did?: string) => boolean;
 export * from './share-content-canonical';
+export * from './consent-flow-contract-updates';
 export * from './credential-materialization';
+export * from './age-policy';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAgB,UAAU,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,YAA6B,CAAC;AAE/D,8DAA8D;AAC9D,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,KAAG,IAAI,IAAI,GAEnD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,eA8B/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,OAAO,KAAG,OAQjD,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,GAAI,KAAK,EAAE,GAAG,UAAU,QAMzD,CAAC;AAGF,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AAGxC,cAAc,aAAa,CAAC;AAG5B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,OAAO,CAAC;AACtB,cAAc,eAAe,CAAC;AAG9B,cAAc,qBAAqB,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,OAK1C,CAAC;AAEF,cAAc,2BAA2B,CAAC;AAE1C,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAgB,UAAU,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,YAA6B,CAAC;AAE/D,8DAA8D;AAC9D,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,KAAG,IAAI,IAAI,GAEnD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,eA8B/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,OAAO,KAAG,OAQjD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAG,mBAA4B,CAAC;AAEvE,iGAAiG;AACjG,eAAO,MAAM,2BAA2B,GAAI,YAAY,OAAO,KAAG,OAGc,CAAC;AAEjF,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,GAAI,KAAK,EAAE,GAAG,UAAU,QAMzD,CAAC;AAGF,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AAGxC,cAAc,aAAa,CAAC;AAG5B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,OAAO,CAAC;AACtB,cAAc,eAAe,CAAC;AAG9B,cAAc,qBAAqB,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,OAK1C,CAAC;AAEF,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAEhD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/helpers",
-    "version": "1.7.3",
+    "version": "1.8.0",
     "description": "Shared helpers for LearnCard packages",
     "type": "module",
     "main": "./dist/index.cjs",
@@ -54,8 +54,9 @@
     "dependencies": {
         "@noble/hashes": "^1.8.0",
         "@sd-jwt/decode": "^0.19.0",
-        "@learncard/types": "5.24.2",
+        "@learncard/types": "6.0.0",
         "@trpc/server": "11.8.0",
+        "moment": "^2.29.4",
         "immer": "^10.0.3",
         "use-immer": "^0.9.0",
         "zod": "4.6.6"

package/src/age-policy.ts

@@ -0,0 +1,88 @@
+import moment from 'moment';
+
+// Canonical GDPR age-of-consent thresholds for EU countries.
+export const GDPR_AGE_LIMIT: Record<string, number> = {
+    Germany: 16,
+    France: 15,
+    Spain: 14,
+    Ireland: 13,
+    Netherlands: 16,
+    Austria: 14,
+    Italy: 14,
+    Sweden: 13,
+};
+
+export const DEFAULT_EU_AGE_LIMIT = 16;
+export const GDPR_AGE_LIMIT_BY_CODE: Record<string, number> = {
+    DE: 16,
+    FR: 15,
+    ES: 14,
+    IE: 13,
+    NL: 16,
+    AT: 14,
+    IT: 14,
+    SE: 13,
+};
+
+export const EU_COUNTRY_CODES = [
+    'AT',
+    'BE',
+    'BG',
+    'HR',
+    'CY',
+    'CZ',
+    'DK',
+    'EE',
+    'FI',
+    'FR',
+    'DE',
+    'GR',
+    'HU',
+    'IE',
+    'IT',
+    'LV',
+    'LT',
+    'LU',
+    'MT',
+    'NL',
+    'PL',
+    'PT',
+    'RO',
+    'SK',
+    'SI',
+    'ES',
+    'SE',
+];
+
+/** EU countries use the established GDPR threshold; other countries default to 18. */
+export const getMinorAgeThreshold = (countryCode?: string): number => {
+    if (countryCode && EU_COUNTRY_CODES.includes(countryCode)) {
+        return GDPR_AGE_LIMIT_BY_CODE[countryCode] ?? DEFAULT_EU_AGE_LIMIT;
+    }
+    return 18;
+};
+
+/** Returns completed years for a valid ISO date/timestamp, or NaN if invalid/future. */
+export const calculateAgeFromISODate = (dob: string, now: Date = new Date()): number => {
+    // Keep the ISO forms accepted by the existing profile/forms parser, including
+    // compact, week and ordinal dates. parseZone preserves the DOB's calendar day
+    // instead of shifting it with the browser/server timezone.
+    const parsed = moment.parseZone(dob, moment.ISO_8601, true);
+    if (!parsed.isValid()) return Number.NaN;
+    const year = parsed.year();
+    const month = parsed.month() + 1;
+    const day = parsed.date();
+    const birth = new Date(0);
+    birth.setUTCFullYear(year, month - 1, day);
+    birth.setUTCHours(0, 0, 0, 0);
+    const today = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+    if (birth > today) return Number.NaN;
+    let age = today.getUTCFullYear() - year;
+    if (
+        today.getUTCMonth() < month - 1 ||
+        (today.getUTCMonth() === month - 1 && today.getUTCDate() < day)
+    ) {
+        age--;
+    }
+    return age;
+};

package/src/consent-flow-contract-updates.ts

@@ -0,0 +1,472 @@
+import type {
+    ConsentFlowContract,
+    ConsentFlowContractChangeKind,
+    ConsentFlowContractDetailChange,
+    ConsentFlowContractDiff,
+    ConsentFlowContractScope,
+    ConsentFlowContractUpdatePreview,
+} from '@learncard/types';
+
+/** Whether a published optional-choice proposal window has not yet expired. */
+export const hasOpenNewOptionsWindow = (
+    newOptionsUntil: string | undefined,
+    now = Date.now()
+): boolean => Boolean(newOptionsUntil && Date.parse(newOptionsUntil) > now);
+
+export type ConsentFlowContractSnapshot = {
+    contract: ConsentFlowContract;
+    name: string;
+    subtitle?: string;
+    description?: string;
+    reasonForAccessing?: string;
+    image?: string;
+    needsGuardianConsent?: boolean;
+    redirectUrl?: string;
+    frontDoorBoostUri?: string;
+    expiresAt?: string;
+    /** Stable URI/id identity is preferred; URI/id-bearing objects are canonicalized. */
+    autoboosts?: unknown[];
+    writers?: string[];
+};
+
+const scopes = (contract: ConsentFlowContract): ConsentFlowContractScope[] => {
+    const result: ConsentFlowContractScope[] = [];
+    for (const area of ['read', 'write'] as const) {
+        const access = contract[area];
+        for (const [key, config] of Object.entries(access.credentials.categories)) {
+            result.push({
+                area,
+                type: 'credential',
+                key,
+                required: config.required,
+                reason: config.reason,
+            });
+        }
+        for (const [key, config] of Object.entries(access.personal)) {
+            result.push({
+                area,
+                type: 'personal',
+                key,
+                required: config.required,
+                reason: config.reason,
+            });
+        }
+    }
+    return result.sort((a, b) => scopeKey(a).localeCompare(scopeKey(b)));
+};
+
+const scopeKey = ({ area, type, key }: ConsentFlowContractScope): string =>
+    `${area}:${type}:${key}`;
+
+const diffScopes = (
+    previous: ConsentFlowContractScope[],
+    current: ConsentFlowContractScope[]
+): ConsentFlowContractDiff => {
+    const before = new Map(previous.map(scope => [scopeKey(scope), scope]));
+    const after = new Map(current.map(scope => [scopeKey(scope), scope]));
+    const added: ConsentFlowContractScope[] = [];
+    const removed: ConsentFlowContractScope[] = [];
+    const changed: ConsentFlowContractScope[] = [];
+    for (const [key, scope] of after) {
+        const old = before.get(key);
+        if (!old) added.push(scope);
+        else if (old.required !== scope.required || old.reason !== scope.reason)
+            changed.push(scope);
+    }
+    for (const [key, scope] of before) if (!after.has(key)) removed.push(scope);
+    const sort = (list: ConsentFlowContractScope[]) =>
+        list.sort((a, b) => scopeKey(a).localeCompare(scopeKey(b)));
+    return { added: sort(added), removed: sort(removed), changed: sort(changed) };
+};
+
+const DETAIL_FIELDS = [
+    'name',
+    'subtitle',
+    'description',
+    'reasonForAccessing',
+    'image',
+    'needsGuardianConsent',
+    'redirectUrl',
+    'frontDoorBoostUri',
+    'expiresAt',
+] as const;
+
+export const diffContractChange = (
+    prev: ConsentFlowContractSnapshot,
+    next: ConsentFlowContractSnapshot
+): ConsentFlowContractDiff => {
+    const details: ConsentFlowContractDetailChange[] = [];
+    for (const field of DETAIL_FIELDS) {
+        const before = field === 'needsGuardianConsent' ? !!prev[field] : prev[field];
+        const after = field === 'needsGuardianConsent' ? !!next[field] : next[field];
+        if (before !== after) details.push({ field, before, after });
+    }
+    for (const field of ['writers', 'autoboosts'] as const) {
+        const before = [...set(prev[field])].sort();
+        const after = [...set(next[field])].sort();
+        if (
+            before.length !== after.length ||
+            before.some((value, index) => value !== after[index])
+        ) {
+            details.push({ field, before, after });
+        }
+    }
+    return {
+        ...diffScopes(scopes(prev.contract), scopes(next.contract)),
+        ...(details.length ? { details } : {}),
+    };
+};
+
+const expiryIsStricter = (previous?: string, next?: string): boolean => {
+    if (!next) return false;
+    if (!previous) return true;
+    const oldTime = Date.parse(previous);
+    const newTime = Date.parse(next);
+    return Number.isFinite(oldTime) && Number.isFinite(newTime) && newTime < oldTime;
+};
+
+const canonicalIdentity = (value: unknown): string => {
+    if (typeof value === 'string') return value;
+    if (value && typeof value === 'object') {
+        if (Array.isArray(value)) return `[${value.map(canonicalIdentity).join(',')}]`;
+        const record = value as Record<string, unknown>;
+        const identity = record.uri ?? record.id ?? record.boostUri;
+        if (typeof identity === 'string') return identity;
+        return `{${Object.keys(record)
+            .sort()
+            .map(key => `${JSON.stringify(key)}:${canonicalIdentity(record[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? String(value);
+};
+
+const set = (values?: unknown[]) => new Set((values ?? []).map(canonicalIdentity));
+
+export const classifyContractChange = (
+    prev: ConsentFlowContractSnapshot,
+    next: ConsentFlowContractSnapshot
+): ConsentFlowContractChangeKind => {
+    const previousScopes = scopes(prev.contract);
+    const diff = diffScopes(previousScopes, scopes(next.contract));
+    const before = new Map(previousScopes.map(scope => [scopeKey(scope), scope]));
+    let requiresConsent =
+        next.name !== prev.name ||
+        next.reasonForAccessing !== prev.reasonForAccessing ||
+        (!prev.needsGuardianConsent && !!next.needsGuardianConsent) ||
+        expiryIsStricter(prev.expiresAt, next.expiresAt) ||
+        next.writers?.some(writer => !prev.writers?.includes(writer)) === true;
+    let expandedOptional = false;
+    for (const scope of diff.added) {
+        if (scope.required) requiresConsent = true;
+        else expandedOptional = true;
+    }
+    for (const scope of diff.changed) {
+        const previous = before.get(scopeKey(scope));
+        if (scope.reason !== previous?.reason || (scope.required && !previous?.required))
+            requiresConsent = true;
+    }
+    const oldBoosts = set(prev.autoboosts);
+    if ([...set(next.autoboosts)].some(boost => !oldBoosts.has(boost))) requiresConsent = true;
+    if (requiresConsent) return 'requires_consent';
+    if (expandedOptional) return 'expanded_optional';
+    return 'relaxed';
+};
+const CANONICAL_SCOPE_COPY: Record<
+    string,
+    { messageKey: string; label: string; description: string }
+> = {
+    TRANSCRIPT: {
+        messageKey: 'transcripts',
+        label: 'Transcripts',
+        description: 'Records of completed courses and learning.',
+    },
+    TRANSCRIPTS: {
+        messageKey: 'transcripts',
+        label: 'Transcripts',
+        description: 'Records of completed courses and learning.',
+    },
+    CERTIFICATE: {
+        messageKey: 'certificates',
+        label: 'Certificates',
+        description: 'Credentials recognizing qualifications or completed learning.',
+    },
+    CERTIFICATES: {
+        messageKey: 'certificates',
+        label: 'Certificates',
+        description: 'Credentials recognizing qualifications or completed learning.',
+    },
+    ACHIEVEMENT: {
+        messageKey: 'achievements',
+        label: 'Achievements',
+        description: 'Milestones earned through effort, skill, or perseverance.',
+    },
+    ACHIEVEMENTS: {
+        messageKey: 'achievements',
+        label: 'Achievements',
+        description: 'Milestones earned through effort, skill, or perseverance.',
+    },
+    SKILL: {
+        messageKey: 'skills',
+        label: 'Skills',
+        description: 'Abilities developed through training, practice, or experience.',
+    },
+    SKILLS: {
+        messageKey: 'skills',
+        label: 'Skills',
+        description: 'Abilities developed through training, practice, or experience.',
+    },
+    'WORK HISTORY': {
+        messageKey: 'workHistory',
+        label: 'Work History',
+        description: 'Professional roles and activities over time.',
+    },
+    'LEARNING HISTORY': {
+        messageKey: 'learningHistory',
+        label: 'Learning History',
+        description: 'Structured programs of learning.',
+    },
+    ID: { messageKey: 'ids', label: 'IDs', description: 'Credentials used to verify identity.' },
+    'SOCIAL BADGE': {
+        messageKey: 'socialBadges',
+        label: 'Social Badges',
+        description: 'Digital labels recognizing participation or group membership.',
+    },
+    'SOCIAL BADGES': {
+        messageKey: 'socialBadges',
+        label: 'Social Badges',
+        description: 'Digital labels recognizing participation or group membership.',
+    },
+    MEMBERSHIP: {
+        messageKey: 'memberships',
+        label: 'Memberships',
+        description: 'Records of memberships.',
+    },
+    MEMBERSHIPS: {
+        messageKey: 'memberships',
+        label: 'Memberships',
+        description: 'Records of memberships.',
+    },
+    ACCOMPLISHMENT: {
+        messageKey: 'accomplishments',
+        label: 'Accomplishments',
+        description: 'Collections of work that showcase skills and experience.',
+    },
+    ACCOMPLISHMENTS: {
+        messageKey: 'accomplishments',
+        label: 'Accomplishments',
+        description: 'Collections of work that showcase skills and experience.',
+    },
+    EXPERIENCES: {
+        messageKey: 'experiences',
+        label: 'Experiences',
+        description: 'Knowledge and skills gained through professional roles and activities.',
+    },
+    ACCOMMODATION: {
+        messageKey: 'accommodations',
+        label: 'Accommodations',
+        description: 'Adjustments made to support accessibility.',
+    },
+    ACCOMMODATIONS: {
+        messageKey: 'accommodations',
+        label: 'Accommodations',
+        description: 'Adjustments made to support accessibility.',
+    },
+    FAMILY: {
+        messageKey: 'family',
+        label: 'Family',
+        description: 'Family profiles connected through shared learning journeys.',
+    },
+    QUALIFICATIONS: {
+        messageKey: 'qualifications',
+        label: 'Qualifications',
+        description: 'Education, training, and professional qualifications.',
+    },
+    GOALS: {
+        messageKey: 'goals',
+        label: 'Goals',
+        description: 'Learning and career goals you want to achieve.',
+    },
+    'PROFESSIONAL TITLE': {
+        messageKey: 'professionalTitle',
+        label: 'Professional title',
+        description: 'The title that describes your professional role.',
+    },
+    'ROLE EXPERIENCE': {
+        messageKey: 'roleExperience',
+        label: 'Role experience',
+        description: 'Experience gained in a particular professional role.',
+    },
+    'WORK EXPERIENCE': {
+        messageKey: 'workExperience',
+        label: 'Work experience',
+        description: 'Your work activities, responsibilities, and experience.',
+    },
+    'PAY RATE': {
+        messageKey: 'payRate',
+        label: 'Pay rate',
+        description: 'Your pay amount and payment period.',
+    },
+    'WORK LIFE BALANCE': {
+        messageKey: 'workLifeBalance',
+        label: 'Work-life balance',
+        description: 'Your preferences for balancing work and personal life.',
+    },
+    'JOB STABILITY': {
+        messageKey: 'jobStability',
+        label: 'Job stability',
+        description: 'Your preferences for job security and stability.',
+    },
+    'SELF-ASSIGNED SKILLS': {
+        messageKey: 'selfAssignedSkills',
+        label: 'Self-assigned skills',
+        description: 'Skills you have added to your own profile.',
+    },
+    'AI-SUMMARY': {
+        messageKey: 'aiSummaries',
+        label: 'AI summaries',
+        description: 'Summaries of your AI-assisted learning sessions.',
+    },
+    'AI-TOPIC': {
+        messageKey: 'aiTopics',
+        label: 'AI topics',
+        description: 'Topics explored in your AI-assisted learning.',
+    },
+    'AI-ASSESSMENT': {
+        messageKey: 'aiAssessments',
+        label: 'AI assessments',
+        description: 'Assessments from your AI-assisted learning.',
+    },
+    'AI INSIGHT': {
+        messageKey: 'aiInsights',
+        label: 'AI insights',
+        description: 'Insights about your learning progress and skills.',
+    },
+    'LEARNING-PATHWAY': {
+        messageKey: 'learningPathways',
+        label: 'Learning pathways',
+        description: 'Plans and steps toward your learning goals.',
+    },
+};
+
+const PERSONAL_SCOPE_COPY: Record<
+    string,
+    { messageKey: string; label: string; description: string }
+> = {
+    NAME: { messageKey: 'name', label: 'Name', description: 'Your name.' },
+    EMAIL: { messageKey: 'email', label: 'Email', description: 'Your email address.' },
+    IMAGE: {
+        messageKey: 'profilePhoto',
+        label: 'Profile photo',
+        description: 'Your profile photo.',
+    },
+    'PROFILE IMAGE': {
+        messageKey: 'profilePhoto',
+        label: 'Profile photo',
+        description: 'Your profile photo.',
+    },
+    'PROFILE PHOTO': {
+        messageKey: 'profilePhoto',
+        label: 'Profile photo',
+        description: 'Your profile photo.',
+    },
+};
+
+const scopeCopy = (
+    scope: ConsentFlowContractScope,
+    translate?: (key: string, values?: Record<string, unknown>) => string
+) => {
+    const copy = (scope.type === 'personal' ? PERSONAL_SCOPE_COPY : CANONICAL_SCOPE_COPY)[
+        scope.key.toUpperCase()
+    ];
+    if (!copy) return { label: scope.key, description: '' };
+    if (!translate) return copy;
+    const prefix = `consentUpdate.scope.${copy.messageKey}`;
+    return {
+        label: translate(`${prefix}.label`),
+        description: translate(`${prefix}.description`),
+    };
+};
+
+export const buildContractUpdatePreview = ({
+    name,
+    kind,
+    diff,
+    status,
+    translate,
+}: {
+    name: string;
+    kind: ConsentFlowContractChangeKind;
+    diff: ConsentFlowContractDiff;
+    status?: string;
+    /** Clients localize structured changes; the API retains canonical English copy. */
+    translate?: (key: string, values?: Record<string, unknown>) => string;
+}): ConsentFlowContractUpdatePreview => {
+    const text = (key: string, fallback: string, values?: Record<string, unknown>) =>
+        translate?.(`consentUpdate.${key}`, values) ?? fallback;
+    const label = (scope: ConsentFlowContractScope) => scopeCopy(scope, translate).label;
+    const addedScopeCount = diff.added.length;
+    const onlyAddedScopes = diff.changed.length === 0 && !diff.details?.length;
+    let headline: string;
+    let subhead: string;
+    let primaryLabel: string;
+    if (status === 'suspended') {
+        headline = text('headline.paused', `${name}'s access is paused`, { name });
+        subhead = text('subhead.reconnect', 'Approve the update to reconnect.');
+        primaryLabel = text('action.reconnect', 'Reconnect');
+    } else if (kind === 'requires_consent' && addedScopeCount === 1 && onlyAddedScopes) {
+        const scope = diff.added[0]!;
+        const values = { name, label: label(scope) };
+        headline =
+            scope.area === 'read'
+                ? text('headline.read', `${name} is asking to see your ${values.label}`, values)
+                : text(
+                      'headline.write',
+                      `${name} is asking to add ${values.label} to your account`,
+                      values
+                  );
+        subhead = '';
+        primaryLabel = text('action.allow', 'Allow');
+    } else if (kind === 'requires_consent' && addedScopeCount > 1 && onlyAddedScopes) {
+        headline = text('headline.multiple', `${name} is asking for more access`, { name });
+        subhead = text('subhead.newItems', `${addedScopeCount} new items`, {
+            count: addedScopeCount,
+        });
+        primaryLabel = text('action.allowAccess', 'Allow access');
+    } else if (kind === 'requires_consent') {
+        headline = text('headline.changed', `${name} changed its request`, { name });
+        subhead = text('subhead.review', "Review what's different.");
+        primaryLabel = text('action.allow', 'Allow');
+    } else if (kind === 'expanded_optional') {
+        headline = text('headline.optional', `${name} has a new option`, { name });
+        subhead = text(
+            'subhead.optional',
+            'Turn it on if you want. Nothing changes unless you do.'
+        );
+        primaryLabel = text('action.continue', 'Continue');
+    } else {
+        const removed = diff.removed[0];
+        headline = removed
+            ? text('headline.removed', `${name} now sees less`, { name })
+            : text('headline.changed', `${name} changed its request`, { name });
+        subhead = removed
+            ? text('subhead.removed', `Stopped asking for ${label(removed)}.`, {
+                  label: label(removed),
+              })
+            : text('subhead.changed', 'Its request has changed.');
+        primaryLabel = text('action.done', 'Done');
+    }
+    const row = (scope: ConsentFlowContractScope, change: 'added' | 'removed' | 'changed') => {
+        const copy = scopeCopy(scope, translate);
+        return { scope, change, label: copy.label, subtitle: scope.reason || copy.description };
+    };
+    return {
+        headline,
+        subhead,
+        rows: [
+            ...diff.added.map(scope => row(scope, 'added')),
+            ...diff.removed.map(scope => row(scope, 'removed')),
+            ...diff.changed.map(scope => row(scope, 'changed')),
+        ],
+        primaryLabel,
+    };
+};