@learncard/types 5.22.0 → 5.23.1

package/src/lcn.ts

@@ -714,12 +714,14 @@ export const ConsentFlowContractDetailsValidator = z.object({
     expiresAt: z.string().optional(),
     autoBoosts: z.string().array().optional(),
     writers: z.array(LCNProfileValidator).optional(),
+    recipients: z.array(LCNPublicProfileValidator.extend({ did: z.string() })).optional(),
+    audienceVersion: z.number().int().nonnegative().optional(),
 });
 export type ConsentFlowContractDetails = z.infer<typeof ConsentFlowContractDetailsValidator>;
 export type ConsentFlowContractDetailsInput = z.input<typeof ConsentFlowContractDetailsValidator>;
 
 export const ConsentFlowContractRequestStatusValidator = z
-    .enum(['pending', 'accepted', 'denied'])
+    .enum(['pending', 'accepted', 'denied', 'cancelled'])
     .nullable();
 export type ConsentFlowContractRequestStatus = z.infer<
     typeof ConsentFlowContractRequestStatusValidator
@@ -730,7 +732,51 @@ export type ConsentFlowContractRequestReadStatus = z.infer<
     typeof ConsentFlowContractRequestReadStatusValidator
 >;
 
-export const ConsentFlowContractRequestForProfileValidator = z.object({
+/** Durable referral identity captured on consent history and correlated events. */
+export const ConsentFlowReferralValidator = z.object({
+    requestId: z.string(),
+    requestedBy: z.string(),
+    externalReferenceId: z.string().max(256).optional(),
+});
+export type ConsentFlowReferral = z.infer<typeof ConsentFlowReferralValidator>;
+
+export const ContractRequestFieldsValidator = ConsentFlowReferralValidator.partial().extend({
+    requestedAt: z.string().optional(),
+    message: z.string().max(500).optional(),
+});
+export type ContractRequestFields = z.infer<typeof ContractRequestFieldsValidator>;
+
+export const SendContractRequestValidator = z.object({
+    contractUri: z.string(),
+    targetProfileId: z.string(),
+    externalReferenceId: z.string().trim().min(1).max(256).optional(),
+    message: z.string().trim().max(500).optional(),
+});
+export type SendContractRequest = z.infer<typeof SendContractRequestValidator>;
+
+export const ConsentFlowWebhookMetadataValidator = z.object({
+    eventId: z.string(),
+    deliveryKey: z.string(),
+    event: z.enum([
+        'request_sent',
+        'request_accepted',
+        'request_denied',
+        'request_cancelled',
+        'consent_created',
+        'consent_updated',
+        'consent_withdrawn',
+        'credentials_synced',
+    ]),
+    contractUri: z.string(),
+    termsUri: z.string().optional(),
+    requestId: z.string().optional(),
+    requestedBy: z.string().optional(),
+    externalReferenceId: z.string().optional(),
+    recipientRole: z.enum(['owner', 'recipient', 'requester', 'target']),
+});
+export type ConsentFlowWebhookMetadata = z.infer<typeof ConsentFlowWebhookMetadataValidator>;
+
+export const ConsentFlowContractRequestForProfileValidator = ContractRequestFieldsValidator.extend({
     profile: LCNProfileValidator,
     status: ConsentFlowContractRequestStatusValidator,
     readStatus: ConsentFlowContractRequestReadStatusValidator.optional(),
@@ -803,6 +849,7 @@ export const PaginatedConsentFlowTermsValidator = PaginationResponseValidator.ex
             expiresAt: z.string().optional(),
             oneTime: z.boolean().optional(),
             terms: ConsentFlowTermsValidator,
+            referral: ConsentFlowReferralValidator.optional(),
             contract: ConsentFlowContractDetailsValidator,
             uri: z.string(),
             consenter: LCNProfileValidator,
@@ -962,6 +1009,7 @@ export const ConsentFlowTransactionValidator = z.object({
     oneTime: z.boolean().optional(),
     terms: ConsentFlowTermsValidator.optional(),
     guardianApproval: ConsentFlowGuardianApprovalValidator.optional(),
+    referral: ConsentFlowReferralValidator.optional(),
     id: z.string(),
     action: ConsentFlowTransactionActionValidator,
     date: z.string(),
@@ -974,6 +1022,7 @@ export const HolderExportConsentRecordValidator = z.object({
     status: ConsentFlowTermsStatusValidator,
     contract: ConsentFlowContractDetailsValidator,
     terms: ConsentFlowTermsValidator,
+    referral: ConsentFlowReferralValidator.optional(),
     transactions: ConsentFlowTransactionValidator.array(),
 });
 export type HolderExportConsentRecord = z.infer<typeof HolderExportConsentRecordValidator>;
@@ -2188,7 +2237,7 @@ export const AppStoreListingSubmitterValidator = z.object({
 
 export type AppStoreListingSubmitter = z.infer<typeof AppStoreListingSubmitterValidator>;
 
-export const AppStoreListingValidator = z.object({
+const AppStoreListingFieldsValidator = z.object({
     listing_id: z.string(),
     slug: z.string().optional(),
     display_name: z.string(),
@@ -2215,12 +2264,35 @@ export const AppStoreListingValidator = z.object({
     contact_email: z.string().email().optional(),
 });
 
+export const PendingListingUpdateStatusValidator = z.enum(['DRAFT', 'PENDING_REVIEW']);
+export type PendingListingUpdateStatus = z.infer<typeof PendingListingUpdateStatusValidator>;
+
+/** Changes to a live app that only take effect once an admin approves them. */
+export const PendingListingUpdateValidator = z.object({
+    status: PendingListingUpdateStatusValidator,
+    submitted_at: z.string().optional(),
+    changes: AppStoreListingFieldsValidator.omit({
+        listing_id: true,
+        app_listing_status: true,
+        promotion_level: true,
+        submitted_at: true,
+        submitter: true,
+    }).partial(),
+    manifest_version: z.number().int().min(1).optional(),
+});
+export type PendingListingUpdate = z.infer<typeof PendingListingUpdateValidator>;
+
+export const AppStoreListingValidator = AppStoreListingFieldsValidator.extend({
+    pending_update: PendingListingUpdateValidator.optional(),
+});
+
 export type AppStoreListing = z.infer<typeof AppStoreListingValidator>;
 
 export const AppStoreListingCreateValidator = AppStoreListingValidator.omit({
     listing_id: true,
     app_listing_status: true,
     promotion_level: true,
+    pending_update: true,
 });
 
 export type AppStoreListingCreateType = z.infer<typeof AppStoreListingCreateValidator>;
@@ -2229,6 +2301,7 @@ export const AppStoreListingUpdateValidator = AppStoreListingValidator.partial()
     listing_id: true,
     app_listing_status: true,
     promotion_level: true,
+    pending_update: true,
 });
 
 export type AppStoreListingUpdateType = z.infer<typeof AppStoreListingUpdateValidator>;
@@ -2264,13 +2337,116 @@ export const AppBoostValidator = z.object({
 export type AppBoost = z.infer<typeof AppBoostValidator>;
 
 // App Event Types (discriminated union for type safety)
-export const SendCredentialEventValidator = z.object({
+export const InlineWalletCategoryValidator = z.enum([
+    'Achievement',
+    'Skill',
+    'ID',
+    'Learning History',
+    'Work History',
+    'Social Badges',
+    'Membership',
+    'Accomplishment',
+    'Experiences',
+    'Accommodation',
+    'Family',
+]);
+
+export const InlineAlignmentValidator = z
+    .object({
+        name: z.string(),
+        url: z.string(),
+        framework: z.string().optional(),
+        code: z.string().optional(),
+    })
+    .passthrough();
+
+export const InlineEvidenceValidator = z
+    .object({
+        id: z.string().optional(),
+        name: z.string().optional(),
+        narrative: z.string().optional(),
+    })
+    .passthrough();
+
+export const InlineWalletSkillTagValidator = z
+    .object({
+        frameworkId: z.string(),
+        id: z.string(),
+        proficiencyLevel: z.string().optional(),
+    })
+    .passthrough();
+
+export const SimpleInlineCredentialTemplateValidator = z
+    .object({
+        rawCredential: z.undefined().optional(),
+        name: z.string(),
+        description: z.string().optional(),
+        image: z.string().optional(),
+        issuerName: z.string().optional(),
+        achievementType: z.string().optional(),
+        category: InlineWalletCategoryValidator.optional(),
+        criteria: z
+            .object({
+                narrative: z.string().optional(),
+                url: z.string().optional(),
+            })
+            .passthrough()
+            .optional(),
+        alignments: z.array(InlineAlignmentValidator).optional(),
+        tags: z.array(z.string()).optional(),
+        activity: z
+            .object({
+                startDate: z.string().optional(),
+                endDate: z.string().optional(),
+            })
+            .passthrough()
+            .optional(),
+        credits: z
+            .object({
+                earned: z.union([z.number(), z.string()]).optional(),
+                available: z.union([z.number(), z.string()]).optional(),
+            })
+            .passthrough()
+            .optional(),
+        validUntil: z.string().optional(),
+        evidence: z.array(InlineEvidenceValidator).optional(),
+        walletSkills: z.array(InlineWalletSkillTagValidator).optional(),
+    })
+    .passthrough();
+
+export const RawInlineCredentialTemplateValidator = z
+    .object({
+        rawCredential: z.record(z.string(), z.unknown()),
+        category: InlineWalletCategoryValidator.optional(),
+        walletSkills: z.array(InlineWalletSkillTagValidator).optional(),
+    })
+    .passthrough();
+
+export const InlineCredentialTemplateValidator = z.union([
+    RawInlineCredentialTemplateValidator,
+    SimpleInlineCredentialTemplateValidator,
+]);
+
+export const LegacySendCredentialEventValidator = z.object({
     type: z.literal('send-credential'),
     templateAlias: z.string(),
     templateData: z.record(z.string(), z.unknown()).optional(),
     preventDuplicateClaim: z.boolean().optional(),
 });
 
+export const InlineSendCredentialEventValidator = z.object({
+    type: z.literal('send-credential'),
+    alias: z.string(),
+    template: InlineCredentialTemplateValidator,
+    templateData: z.record(z.string(), z.unknown()).optional(),
+    preventDuplicateClaim: z.boolean().optional(),
+});
+
+export const SendCredentialEventValidator = z.union([
+    LegacySendCredentialEventValidator,
+    InlineSendCredentialEventValidator,
+]);
+
 export type SendCredentialEvent = z.infer<typeof SendCredentialEventValidator>;
 
 export const CheckCredentialEventValidator = z
@@ -2425,8 +2601,168 @@ export const GetCountersEventValidator = z.object({
 
 export type GetCountersEvent = z.infer<typeof GetCountersEventValidator>;
 
+export const ConsentRequestWalletCategoryValidator = z.enum([
+    'Achievement',
+    'Skill',
+    'ID',
+    'Learning History',
+    'Work History',
+    'Social Badges',
+    'Membership',
+    'Accomplishment',
+    'Experiences',
+    'Accommodation',
+    'Family',
+]);
+
+export const ConsentRequestPersonalFieldValidator = z.enum([
+    'name',
+    'email',
+    'phone',
+    'birthDate',
+    'country',
+    'avatar',
+]);
+
+export const ConsentRequestValidator = z.object({
+    read: z
+        .object({
+            credentialCategories: z.array(ConsentRequestWalletCategoryValidator).optional(),
+            personalFields: z.array(ConsentRequestPersonalFieldValidator).optional(),
+        })
+        .optional(),
+    write: z
+        .object({
+            credentialCategories: z.array(ConsentRequestWalletCategoryValidator).optional(),
+        })
+        .optional(),
+    reason: z.string().optional(),
+});
+
+export type ConsentRequest = z.infer<typeof ConsentRequestValidator>;
+
+export const NormalizedConsentScopesValidator = z.object({
+    read: z.object({
+        credentialCategories: z.array(ConsentRequestWalletCategoryValidator).default([]),
+        personalFields: z.array(ConsentRequestPersonalFieldValidator).default([]),
+    }),
+    write: z.object({
+        credentialCategories: z.array(ConsentRequestWalletCategoryValidator).default([]),
+    }),
+});
+
+export type NormalizedConsentScopes = z.infer<typeof NormalizedConsentScopesValidator>;
+
+export const CapturedTemplateRecordValidator = z
+    .object({
+        alias: z.string(),
+        template: InlineCredentialTemplateValidator,
+        version: z.number().int().min(1),
+        lastUsedAt: z.string(),
+    })
+    .passthrough();
+
+export type CapturedTemplateRecord = z.infer<typeof CapturedTemplateRecordValidator>;
+
+export const CapturedConsentRecordValidator = z
+    .object({
+        scopes: NormalizedConsentScopesValidator,
+        reason: z.string().optional(),
+        lastUsedAt: z.string(),
+    })
+    .passthrough();
+
+export type CapturedConsentRecord = z.infer<typeof CapturedConsentRecordValidator>;
+
+export const AppManifestValidator = z
+    .object({
+        manifestVersion: z.literal(1),
+        appUrl: z.string(),
+        appKey: z.string().max(200).optional(),
+        suggestedName: z.string().optional(),
+        suggestedIconUrl: z.string().optional(),
+        permissions: z.array(z.string()).default([]),
+        templates: z.array(CapturedTemplateRecordValidator).default([]),
+        consentRequests: z.array(CapturedConsentRecordValidator).default([]),
+        usedConsentContract: z.boolean().optional(),
+        featuresLaunched: z.array(z.string()).default([]),
+        counterKeys: z.array(z.string()).default([]),
+        usedLearnerContext: z.boolean(),
+        usedNotifications: z.boolean(),
+        firstCapturedAt: z.string(),
+        lastUpdatedAt: z.string(),
+    })
+    .passthrough();
+
+export type AppManifest = z.infer<typeof AppManifestValidator>;
+
+export const AppManifestVersionStatusValidator = z.enum(['draft', 'active', 'superseded']);
+export type AppManifestVersionStatus = z.infer<typeof AppManifestVersionStatusValidator>;
+
+export const AppManifestVersionValidator = z.object({
+    id: z.string(),
+    version: z.number().int().min(1),
+    manifestHash: z.string(),
+    manifest: AppManifestValidator,
+    status: AppManifestVersionStatusValidator,
+    createdAt: z.string(),
+    activatedAt: z.string().optional(),
+});
+
+export type AppManifestVersion = z.infer<typeof AppManifestVersionValidator>;
+
+const AppManifestStringDiffValidator = z.object({
+    added: z.array(z.string()),
+    removed: z.array(z.string()),
+    changed: z.array(z.string()),
+});
+
+export const AppManifestTemplateRefValidator = z.object({
+    alias: z.string(),
+    version: z.number().int().min(1),
+});
+
+export type AppManifestTemplateRef = z.infer<typeof AppManifestTemplateRefValidator>;
+
+export const AppManifestTemplateChangeValidator = z.object({
+    alias: z.string(),
+    fromVersion: z.number().int().min(1),
+    toVersion: z.number().int().min(1),
+});
+
+export type AppManifestTemplateChange = z.infer<typeof AppManifestTemplateChangeValidator>;
+
+export const AppManifestDiffValidator = z.object({
+    permissions: AppManifestStringDiffValidator,
+    templates: z.object({
+        added: z.array(AppManifestTemplateRefValidator),
+        removed: z.array(AppManifestTemplateRefValidator),
+        changed: z.array(AppManifestTemplateChangeValidator),
+    }),
+    consentScopes: AppManifestStringDiffValidator,
+    featurePaths: AppManifestStringDiffValidator,
+    counterKeys: AppManifestStringDiffValidator,
+    requiresReview: z.boolean(),
+});
+
+export type AppManifestDiff = z.infer<typeof AppManifestDiffValidator>;
+
+export const UpsertConsentContractEventValidator = z.object({
+    type: z.literal('upsert-consent-contract'),
+    scopes: ConsentRequestValidator,
+});
+
+export type UpsertConsentContractEvent = z.infer<typeof UpsertConsentContractEventValidator>;
+
+export const UpsertConsentContractResponseValidator = z.object({
+    contractUri: z.string(),
+    created: z.boolean(),
+});
+
+export type UpsertConsentContractResponse = z.infer<typeof UpsertConsentContractResponseValidator>;
+
 // Add new event types here as the union grows
-export const AppEventValidator = z.discriminatedUnion('type', [
+export const AppEventValidator = z.union([
     SendCredentialEventValidator,
     CheckCredentialEventValidator,
     CheckIssuanceStatusEventValidator,
@@ -2437,6 +2773,7 @@ export const AppEventValidator = z.discriminatedUnion('type', [
     IncrementCounterEventValidator,
     GetCounterEventValidator,
     GetCountersEventValidator,
+    UpsertConsentContractEventValidator,
 ]);
 
 export type AppEvent = z.infer<typeof AppEventValidator>;

package/src/share-links.ts

@@ -592,6 +592,8 @@ export const ShareLinkValidator = z.object({
     version: safeVersion,
     contentVersion: safeVersion,
     status: ShareLinkStatusValidator,
+    attachmentId: z.string().uuid().nullable().optional(),
+    attachmentChunkCount: z.number().int().min(1).max(16).nullable().optional(),
     contentState: ShareContentStateValidator,
     createdAt: z.iso.datetime(),
     updatedAt: z.iso.datetime(),
@@ -618,6 +620,74 @@ export type ShareLink = z.infer<typeof ShareLinkValidator>;
 
 const clientRequestId = z.string().uuid();
 
+/** Opaque, version-bound descriptor; PDF bytes and keys never reach Brain metadata. */
+export const ShareLinkAttachmentValidator = z
+    .object({
+        id: z.string().uuid(),
+        chunkCount: z.number().int().min(1).max(16),
+    })
+    .strict();
+export type ShareLinkAttachment = z.infer<typeof ShareLinkAttachmentValidator>;
+
+const attachmentChunkKey = {
+    id: ShareLinkIdValidator,
+    contentVersion: safeVersion,
+    attachmentId: z.string().uuid(),
+    chunkIndex: z.number().int().min(0).max(15),
+};
+export const ShareLinkAttachmentChunkEnvelopeValidator = ShareEnvelopeValidator.refine(
+    value => (decodedBase64UrlByteLength(value.ct) ?? Infinity) <= 256 * 1024 + SHARE_TAG_BYTES
+);
+export const PutShareLinkAttachmentChunkInputValidator = z
+    .object({
+        ...attachmentChunkKey,
+        chunkCount: z.number().int().min(1).max(16),
+        envelope: ShareLinkAttachmentChunkEnvelopeValidator,
+        ownerEncryptedRecovery: ShareOwnerRecoveryValidator,
+    })
+    .strict()
+    .refine(value => value.chunkIndex < value.chunkCount);
+export type PutShareLinkAttachmentChunkInput = z.infer<
+    typeof PutShareLinkAttachmentChunkInputValidator
+>;
+export const GetShareLinkAttachmentChunkInputValidator = z
+    .object({
+        ...attachmentChunkKey,
+        passcode: z.string().min(4).max(64).optional(),
+        accessToken: z.string().min(1).max(2048).optional(),
+    })
+    .strict();
+export type GetShareLinkAttachmentChunkInput = z.infer<
+    typeof GetShareLinkAttachmentChunkInputValidator
+>;
+export const ShareLinkAttachmentChunkOutputValidator = z
+    .object({
+        ...attachmentChunkKey,
+        envelope: ShareLinkAttachmentChunkEnvelopeValidator,
+        accessToken: z.string().min(1).max(2048).optional(),
+    })
+    .strict();
+export type ShareLinkAttachmentChunkOutput = z.infer<
+    typeof ShareLinkAttachmentChunkOutputValidator
+>;
+export const DeleteShareLinkAttachmentChunksInputValidator = z
+    .object({
+        id: ShareLinkIdValidator,
+        contentVersion: safeVersion,
+        attachmentId: z.string().uuid(),
+        chunkCount: z.number().int().min(1).max(16),
+    })
+    .strict();
+export type DeleteShareLinkAttachmentChunksInput = z.infer<
+    typeof DeleteShareLinkAttachmentChunksInputValidator
+>;
+export const PutShareLinkAttachmentChunkOutputValidator = z
+    .object({ ok: z.literal(true) })
+    .strict();
+export const DeleteShareLinkAttachmentChunksOutputValidator = z
+    .object({ ok: z.boolean() })
+    .strict();
+
 export const CreateShareLinkInputValidator = z
     .object({
         id: ShareLinkIdValidator,
@@ -631,6 +701,7 @@ export const CreateShareLinkInputValidator = z
         contentVersion: z.literal(1),
         envelope: ShareEnvelopeValidator,
         ownerEncryptedRecovery: ShareOwnerRecoveryValidator,
+        attachment: ShareLinkAttachmentValidator.optional(),
     })
     .strict();
 export type CreateShareLinkInput = z.infer<typeof CreateShareLinkInputValidator>;
@@ -655,6 +726,7 @@ export const UpdateShareLinkInputValidator = z
         selectedCount: z.number().int().min(1).max(MAX_SELECTED_CREDENTIALS).optional(),
         envelope: ShareEnvelopeValidator.optional(),
         ownerEncryptedRecovery: ShareOwnerRecoveryValidator.optional(),
+        attachment: ShareLinkAttachmentValidator.optional(),
     })
     .strict()
     .superRefine((value, ctx) => {
@@ -672,6 +744,9 @@ export const UpdateShareLinkInputValidator = z
                     'content replacement requires contentVersion, selectedCount, envelope and ownerEncryptedRecovery together',
             });
         }
+        if (value.attachment !== undefined && provided !== 4) {
+            ctx.addIssue({ code: 'custom', message: 'attachment requires a content replacement' });
+        }
     });
 export type UpdateShareLinkInput = z.infer<typeof UpdateShareLinkInputValidator>;
 

package/src/vc.test.ts

@@ -1,17 +1,24 @@
 import { expect, test } from 'vitest';
 import { ProofValidator } from './vc';
 
-test('only final ecdsa-rdfc-2019 DataIntegrityProofs may omit created', () => {
+test.each([
+    'ecdsa-rdfc-2019',
+    'ecdsa-jcs-2019',
+    'ecdsa-sd-2023',
+    'eddsa-rdfc-2022',
+    'eddsa-jcs-2022',
+    'bbs-2023',
+])('final %s DataIntegrityProofs may omit created', cryptosuite => {
     const proof = {
         type: 'DataIntegrityProof',
-        cryptosuite: 'ecdsa-rdfc-2019',
+        cryptosuite,
         proofPurpose: 'authentication',
         verificationMethod: 'did:example:holder#key',
         proofValue: 'zSignature',
     };
 
     expect(ProofValidator.parse(proof)).toEqual(proof);
-    const legacy = { ...proof, cryptosuite: 'eddsa-rdfc-2022' };
+    const legacy = { ...proof, cryptosuite: 'unknown-suite' };
     expect(ProofValidator.safeParse(legacy).success).toBe(false);
     expect(ProofValidator.safeParse({ ...legacy, created: '2026-01-01T00:00:00Z' }).success).toBe(
         true

package/src/vc.ts

@@ -200,7 +200,19 @@ export const ProofValidator = z
     .superRefine((proof, ctx) => {
         if (
             proof.created === undefined &&
-            (proof.type !== 'DataIntegrityProof' || proof.cryptosuite !== 'ecdsa-rdfc-2019')
+            // These standardized Data Integrity suites make created optional.
+            // Keep the prior requirement for legacy and unknown proof suites.
+            // https://www.w3.org/TR/vc-di-eddsa/#proof-configuration-eddsa-jcs-2022
+            // https://www.w3.org/TR/vc-di-bbs/#proof-configuration
+            (proof.type !== 'DataIntegrityProof' ||
+                ![
+                    'ecdsa-rdfc-2019',
+                    'ecdsa-jcs-2019',
+                    'ecdsa-sd-2023',
+                    'eddsa-rdfc-2022',
+                    'eddsa-jcs-2022',
+                    'bbs-2023',
+                ].includes(proof.cryptosuite as string))
         ) {
             ctx.addIssue({
                 code: 'custom',