@learncard/network-brain-service 4.1.3 → 5.0.0

package/src/routes/workflows.ts

@@ -27,7 +27,7 @@ import {
     isClaimLinkAlreadySetForBoost,
     getClaimLinkSAInfoForBoost,
     getClaimLinkGeneratorProfileId,
-    useClaimLinkForBoost,
+    useClaimLinkForBoost as claimLinkForBoost,
 } from '@cache/claim-links';
 
 import { validateInboxClaimToken } from '@helpers/contact-method.helpers';
@@ -56,6 +56,7 @@ import { logCredentialClaimed, logCredentialFailed } from '@helpers/activity.hel
 import { handleConnectionPromptsForCredentialClaim } from '@helpers/connectionPrompt.helpers';
 import { decryptInboxCredential } from '@helpers/inbox-encryption.helpers';
 import { getBitstringStatusListEntries } from '@learncard/helpers';
+import { neogma } from '@instance';
 import {
     EXHAUSTED,
     exhaustExchangeChallengeForToken,
@@ -428,7 +429,7 @@ async function handlePresentationForClaim(
         ).credential as VC;
 
         // Mark the challenge as used
-        await useClaimLinkForBoost(exchangeInfo.boostUri, exchangeInfo.challenge);
+        await claimLinkForBoost(exchangeInfo.boostUri, exchangeInfo.challenge);
 
         const vp = await issueResponsePresentationWithVcs([vc]);
 
@@ -716,16 +717,60 @@ async function handleInboxClaimPresentation(
                     deliveryEncryptionFailed = true;
                     throw error;
                 }
-                const finalized = await finalizeAndWipeInboxCredential(inboxCredential.id, {
-                    recipientDid: holderDid,
-                    credential: encryptedDelivery,
+                const issuerProfile = await getProfileByDid(inboxCredential.issuerDid);
+                if (!issuerProfile) throw new Error('Issuer profile not found');
+                const boost = inboxCredential.boostUri
+                    ? await getBoostByUri(inboxCredential.boostUri)
+                    : undefined;
+                // Reservation is part of delivery, not best-effort indexing. A conflict
+                // must leave escrow pending and must never return the reused credential.
+                const delivery = encryptedDelivery;
+                const statusEntries = getBitstringStatusListEntries(finalCredential);
+                await neogma.getTransaction(null, async tx => {
+                    const finalized = await finalizeAndWipeInboxCredential(
+                        inboxCredential.id,
+                        {
+                            recipientDid: holderDid,
+                            credential: delivery,
+                        },
+                        {},
+                        tx
+                    );
+                    if (!finalized) throw new Error('Inbox credential is no longer pending');
+                    const credentialInstance =
+                        statusEntries.length > 0 || (holderProfile && boost)
+                            ? await storeCredential(
+                                  {
+                                      kind: 'issued-credential',
+                                      credential: delivery,
+                                      statusEntries,
+                                  },
+                                  tx,
+                                  issuerProfile.profileId
+                              )
+                            : undefined;
+                    if (holderProfile) {
+                        await createClaimedRelationship(
+                            holderProfile.profileId,
+                            inboxCredential.id,
+                            claimToken,
+                            tx
+                        );
+                        if (boost && credentialInstance) {
+                            await createBoostInstanceOfRelationship(credentialInstance, boost, tx);
+                            await createSentCredentialRelationship(
+                                { type: 'profile', profile: issuerProfile },
+                                holderProfile,
+                                credentialInstance,
+                                undefined,
+                                undefined,
+                                undefined,
+                                tx
+                            );
+                        }
+                    }
                 });
-                if (!finalized) throw new Error('Inbox credential is no longer pending');
-            }
-
-            // Record the claim only after finalization succeeds so failed compare-and-swap
-            // attempts cannot leave a misleading audit relationship behind.
-            if (holderProfile) {
+            } else if (holderProfile) {
                 await createClaimedRelationship(
                     holderProfile.profileId,
                     inboxCredential.id,
@@ -733,38 +778,8 @@ async function handleInboxClaimPresentation(
                 );
             }
 
-            // Store credential and create boost relationship if this was a boost issuance
-            const boostUri = inboxCredential.boostUri;
-            if (!inboxCredential.refreshId && holderProfile && boostUri) {
-                try {
-                    const boost = await getBoostByUri(boostUri);
-                    const issuerProfile = await getProfileByDid(inboxCredential.issuerDid);
-
-                    if (boost && issuerProfile) {
-                        // Store the credential in the database
-                        const credentialInstance = await storeCredential({
-                            kind: 'issued-credential',
-                            credential: encryptedDelivery!,
-                            statusEntries: getBitstringStatusListEntries(finalCredential),
-                        });
-
-                        // Create the boost instance relationship
-                        await createBoostInstanceOfRelationship(credentialInstance, boost);
-
-                        // Create the sent/received credential relationship
-                        await createSentCredentialRelationship(
-                            { type: 'profile', profile: issuerProfile },
-                            holderProfile,
-                            credentialInstance
-                        );
-                    }
-                } catch {
-                    // Escrow is already wiped; preserve delivery even if indexing fails.
-                    console.error('Failed to index claimed inbox boost', inboxCredential.id);
-                }
-            }
-
             // Log CLAIMED activity - chain to original activityId/integrationId if available
+            const boostUri = inboxCredential.boostUri;
             // activityId and integrationId are stored on the inbox credential
             const activityId = inboxCredential.activityId;
             const integrationId = inboxCredential.integrationId;
@@ -805,11 +820,11 @@ async function handleInboxClaimPresentation(
             // Trigger webhook if configured
             if (inboxCredential.webhookUrl) {
                 try {
-                    const learnCard = await getLearnCard();
+                    const webhookLearnCard = await getLearnCard();
                     await addNotificationToQueue({
                         webhookUrl: inboxCredential.webhookUrl,
                         type: LCNNotificationTypeEnumValidator.enum.ISSUANCE_CLAIMED,
-                        from: { did: learnCard.id.did() },
+                        from: { did: webhookLearnCard.id.did() },
                         to: { did: inboxCredential.issuerDid },
                         message: getNotificationMessage(
                             'issuanceClaimed',
@@ -871,7 +886,7 @@ async function handleInboxClaimPresentation(
             try {
                 // Trigger webhook for error if configured
                 if (inboxCredential.webhookUrl) {
-                    const learnCard = await getLearnCard();
+                    const webhookLearnCard = await getLearnCard();
                     const issuanceErrorMsg = getNotificationMessage(
                         'issuanceError',
                         // failedIssuerProfile is the issuer (the webhook recipient),
@@ -883,7 +898,7 @@ async function handleInboxClaimPresentation(
                     await addNotificationToQueue({
                         webhookUrl: inboxCredential.webhookUrl,
                         type: LCNNotificationTypeEnumValidator.enum.ISSUANCE_ERROR,
-                        from: { did: learnCard.id.did() },
+                        from: { did: webhookLearnCard.id.did() },
                         to: { did: inboxCredential.issuerDid },
                         message: {
                             title: issuanceErrorMsg.title,

package/src/services/delivery/adapters/postmark.adapter.test.ts

@@ -1,10 +1,16 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { Notification } from '../delivery.service';
 
-const mocks = vi.hoisted(() => ({ send: vi.fn(), legacySend: vi.fn(), render: vi.fn() }));
+const mocks = vi.hoisted(() => ({
+    send: vi.fn(),
+    legacySend: vi.fn(),
+    render: vi.fn(),
+    stream: vi.fn(),
+}));
 vi.mock('@environment', () => ({ environment: {} }));
 vi.mock('postmark', () => ({
     ServerClient: class {
+        getMessageStream = mocks.stream;
         sendEmail = mocks.send;
         sendEmailWithTemplate = mocks.legacySend;
     },
@@ -25,6 +31,7 @@ beforeEach(() => {
     vi.clearAllMocks();
     mocks.render.mockResolvedValue({ html: '<p>Updated</p>', text: 'Updated', subject: 'Updated' });
     mocks.send.mockResolvedValue({});
+    mocks.stream.mockResolvedValue({ MessageStreamType: 'Broadcasts' });
 });
 
 describe('update email provider attempts', () => {
@@ -52,3 +59,65 @@ describe('update email provider attempts', () => {
         expect(mocks.legacySend).not.toHaveBeenCalled();
     });
 });
+
+describe('campaign provider boundary', () => {
+    const campaignNotification: Notification = {
+        ...notification,
+        templateId: 'campaign-announcement',
+        subject: 'Authored subject',
+        messageStream: 'news',
+        headers: [
+            {
+                Name: 'List-Unsubscribe',
+                Value: '<https://brain.example/campaigns/unsubscribe?token=test>',
+            },
+        ],
+    };
+    it('accepts the Postmark Broadcasts stream type and forwards headers and subject', async () => {
+        await new PostmarkAdapter('test-key').send(campaignNotification);
+        expect(mocks.stream).toHaveBeenCalledWith('news');
+        expect(mocks.send).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Subject: 'Authored subject',
+                MessageStream: 'news',
+                Headers: campaignNotification.headers,
+            })
+        );
+    });
+    it('validates one stream per wave and prepares without sending', async () => {
+        const adapter = new PostmarkAdapter('test-key');
+        await adapter.assertBroadcastStream('news');
+        const first = await adapter.prepareCampaignEmail(campaignNotification);
+        const second = await adapter.prepareCampaignEmail(campaignNotification);
+        expect(mocks.stream).toHaveBeenCalledOnce();
+        expect(mocks.render).toHaveBeenCalledTimes(2);
+        expect(mocks.send).not.toHaveBeenCalled();
+        await first();
+        await second();
+        expect(mocks.send).toHaveBeenCalledTimes(2);
+    });
+    it('does not cache failed stream checks', async () => {
+        const adapter = new PostmarkAdapter('test-key');
+        mocks.stream.mockRejectedValueOnce(new Error('provider private detail'));
+        await expect(adapter.assertBroadcastStream('news')).rejects.toThrow(
+            'stream validation failed'
+        );
+        await adapter.assertBroadcastStream('news');
+        expect(mocks.stream).toHaveBeenCalledTimes(2);
+    });
+    it('rejects a custom transactional stream', async () => {
+        mocks.stream.mockResolvedValue({ MessageStreamType: 'Transactional' });
+        await expect(new PostmarkAdapter('test-key').send(campaignNotification)).rejects.toThrow(
+            'Broadcast'
+        );
+        expect(mocks.send).not.toHaveBeenCalled();
+    });
+    it('never falls back to another send after an uncertain acknowledgement', async () => {
+        mocks.send.mockRejectedValueOnce(new Error('timeout'));
+        await expect(new PostmarkAdapter('test-key').send(campaignNotification)).rejects.toThrow(
+            'timeout'
+        );
+        expect(mocks.send).toHaveBeenCalledOnce();
+        expect(mocks.legacySend).not.toHaveBeenCalled();
+    });
+});

package/src/services/delivery/adapters/postmark.adapter.ts

@@ -42,6 +42,7 @@ const LOCAL_TEMPLATE_MAP: Record<string, TemplateId> = {
     'guardian-email-otp': 'guardian-email-otp',
     'guardian-rejected-credential': 'guardian-rejected-credential',
     'credential-updated': 'credential-updated',
+    'campaign-announcement': 'announcement',
 };
 
 export class PostmarkAdapter implements DeliveryService {
@@ -51,7 +52,65 @@ export class PostmarkAdapter implements DeliveryService {
         this.client = new ServerClient(apiKey);
     }
 
+    private readonly broadcastStreams = new Map<string, Promise<void>>();
+
+    /** Validate once per adapter/wave; failed checks are never cached. */
+    public async assertBroadcastStream(streamId?: string): Promise<void> {
+        if (!streamId || streamId.toLowerCase() === 'outbound')
+            throw new Error('Campaign email requires a broadcast stream');
+        let check = this.broadcastStreams.get(streamId);
+        if (!check) {
+            check = this.client.getMessageStream(streamId).then(stream => {
+                if (stream.MessageStreamType !== 'Broadcasts')
+                    throw new Error('Campaign email requires a Postmark Broadcast stream');
+            });
+            this.broadcastStreams.set(streamId, check);
+        }
+        try {
+            await check;
+        } catch {
+            this.broadcastStreams.delete(streamId);
+            throw new Error('Campaign Postmark Broadcast stream validation failed');
+        }
+    }
+
+    /** Prepare without sending, so callers can render before reserving a recipient. */
+    public async prepareCampaignEmail(notification: Notification): Promise<() => Promise<void>> {
+        await this.assertBroadcastStream(notification.messageStream);
+        const branding = resolveBranding(notification.branding);
+        const rendered = await renderEmail(
+            'announcement',
+            branding,
+            notification.templateModel as TemplateDataMap['announcement'],
+            notification.locale
+        );
+        const brandName =
+            notification.branding?.brandName || environment.POSTMARK_BRAND_NAME || 'LearnCard';
+        const from = notification.branding?.fromDomain
+            ? buildFromAddress(brandName, `support@${notification.branding.fromDomain}`)
+            : buildFromAddress(
+                  brandName,
+                  environment.POSTMARK_FROM_EMAIL || 'support@learningeconomy.io'
+              );
+        return async () => {
+            await this.client.sendEmail({
+                From: from,
+                To: notification.contactMethod.value,
+                Subject: notification.subject ?? rendered.subject,
+                HtmlBody: rendered.html,
+                TextBody: rendered.text,
+                MessageStream: notification.messageStream,
+                Headers: notification.headers,
+            });
+        };
+    }
+
     public async send(notification: Notification): Promise<void> {
+        if (notification.templateId === 'campaign-announcement') {
+            const deliver = await this.prepareCampaignEmail(notification);
+            await deliver();
+            return;
+        }
         const defaultFrom = environment.POSTMARK_FROM_EMAIL || 'support@learningeconomy.io';
         const defaultBrandName = environment.POSTMARK_BRAND_NAME || 'LearnCard';
 
@@ -82,12 +141,18 @@ export class PostmarkAdapter implements DeliveryService {
                     notification.locale
                 );
             } catch (renderError) {
-                console.error(
-                    `[PostmarkAdapter] Local render failed for "${notification.templateId}":`,
-                    renderError
-                );
+                if (notification.templateId !== 'campaign-announcement')
+                    console.error(
+                        `[PostmarkAdapter] Local render failed for "${notification.templateId}":`,
+                        renderError
+                    );
                 // This template is owned locally; there is no legacy provider alias.
-                if (notification.templateId === 'credential-updated') throw renderError;
+                if (
+                    ['credential-updated', 'campaign-announcement'].includes(
+                        notification.templateId
+                    )
+                )
+                    throw renderError;
             }
 
             if (rendered) {
@@ -95,21 +160,28 @@ export class PostmarkAdapter implements DeliveryService {
                     await this.client.sendEmail({
                         From: from,
                         To: notification.contactMethod.value,
-                        Subject: rendered.subject,
+                        Subject: notification.subject ?? rendered.subject,
                         HtmlBody: rendered.html,
                         TextBody: rendered.text,
                         MessageStream: notification.messageStream,
+                        Headers: notification.headers,
                     });
 
                     return;
                 } catch (sendError) {
-                    console.error(
-                        `[PostmarkAdapter] sendEmail API failed for "${notification.templateId}":`,
-                        sendError
-                    );
+                    if (notification.templateId !== 'campaign-announcement')
+                        console.error(
+                            `[PostmarkAdapter] sendEmail API failed for "${notification.templateId}":`,
+                            sendError
+                        );
                     // A lost provider acknowledgement may already have sent the email.
                     // Do not bypass the refresh delivery claim with a second attempt.
-                    if (notification.templateId === 'credential-updated') throw sendError;
+                    if (
+                        ['credential-updated', 'campaign-announcement'].includes(
+                            notification.templateId
+                        )
+                    )
+                        throw sendError;
                 }
             }
         }
@@ -122,6 +194,7 @@ export class PostmarkAdapter implements DeliveryService {
                 TemplateAlias: notification.templateId,
                 TemplateModel: notification.templateModel,
                 MessageStream: notification.messageStream,
+                Headers: notification.headers,
             });
         } catch (error) {
             const detail = error instanceof Error ? error.message : String(error);

package/src/services/delivery/delivery.service.ts

@@ -12,6 +12,8 @@ export interface Notification {
     templateId: string; // e.g., 'universal-inbox-claim'
     templateModel: Record<string, any>; // Data for the template
     messageStream?: string;
+    subject?: string;
+    headers?: Array<{ Name: string; Value: string }>;
     /** Optional tenant branding. When present, emails are rendered locally via @learncard/email-templates. */
     branding?: Partial<TenantBranding>;
     /** Recipient locale (BCP-47), resolved via resolveRecipientLocale. Defaults to English at render time. */
@@ -26,6 +28,8 @@ export const NotificationSchema = z.object({
     templateId: z.string(),
     templateModel: z.record(z.string(), z.any()),
     messageStream: z.string().optional(),
+    subject: z.string().optional(),
+    headers: z.array(z.object({ Name: z.string(), Value: z.string() })).optional(),
     branding: z.record(z.string(), z.any()).optional(),
     locale: z.string().optional(),
 });

package/src/types/campaign.ts

@@ -1,4 +1,5 @@
-import type { CampaignStatus } from '@learncard/types';
+import { z } from 'zod';
+import { CampaignIdValidator, type CampaignStatus } from '@learncard/types';
 
 export type CampaignRecord = {
     id: string;
@@ -15,3 +16,15 @@ export type CampaignRecord = {
 };
 
 export type CampaignAudienceQuery = { match: string; params: Record<string, unknown> };
+
+export const CampaignDispatchJobValidator = z
+    .object({
+        campaignId: CampaignIdValidator,
+        campaignCreatedAt: z.iso.datetime(),
+        channel: z.enum(['notify', 'email']).default('notify'),
+        afterProfileId: z.string().optional(),
+        dispatchId: z.uuid(),
+    })
+    .strict();
+
+export type CampaignDispatchJob = z.input<typeof CampaignDispatchJobValidator>;

package/src/types/consentflowcontract.ts

@@ -5,6 +5,7 @@ import {
     ConsentFlowTransactionActionValidator,
     ConsentFlowGuardianApprovalValidator,
     ConsentFlowReferralValidator,
+    ConsentFlowContractDetailsValidator,
 } from '@learncard/types';
 import { z } from 'zod';
 
@@ -22,6 +23,27 @@ type FlatReferral = {
 
 type FlatConsentTerms = Partial<Record<`terms.${string}`, string | boolean | string[]>>;
 
+export const DbContractVersionValidator = z.object({
+    id: z.string(),
+    version: z.coerce.number().int().positive(),
+    contract: ConsentFlowContractValidator,
+    name: z.string(),
+    subtitle: z.string().optional(),
+    description: z.string().optional(),
+    reasonForAccessing: z.string().optional(),
+    image: z.string().optional(),
+    needsGuardianConsent: z.boolean().optional(),
+    redirectUrl: z.string().optional(),
+    frontDoorBoostUri: z.string().optional(),
+    expiresAt: z.string().optional(),
+    autoboosts: z.array(z.unknown()).default([]),
+    writers: z.array(z.string()).default([]),
+    reason: z.string().optional(),
+    createdAt: z.string(),
+    kind: z.enum(['relaxed', 'expanded_optional', 'requires_consent']).optional(),
+});
+export type DbContractVersionType = z.infer<typeof DbContractVersionValidator>;
+
 export const DbContractValidator = z.object({
     id: z.string(),
     name: z.string(),
@@ -32,16 +54,31 @@ export const DbContractValidator = z.object({
     redirectUrl: z.string().optional(),
     frontDoorBoostUri: z.string().optional(),
     image: z.string().optional(),
-    contract: ConsentFlowContractValidator,
+    // An empty request has no flattened contract.* properties in Neo4j.
+    contract: ConsentFlowContractValidator.prefault({}),
     createdAt: z.string(),
     updatedAt: z.string(),
     expiresAt: z.string().optional(),
     audienceVersion: z.coerce.number().int().nonnegative().optional(),
     hasConsented: z.boolean().optional(),
+    currentVersion: z.coerce.number().int().positive().optional(),
+    status: z.enum(['active', 'retired']).optional(),
+    version: z.coerce.number().int().positive().optional(),
+    latestUpdate: z.preprocess(value => {
+        if (typeof value !== 'string') return value;
+        try {
+            return JSON.parse(value);
+        } catch {
+            return value;
+        }
+    }, ConsentFlowContractDetailsValidator.shape.latestUpdate.optional()),
 });
 
 export type DbContractType = z.infer<typeof DbContractValidator>;
-export type FlatDbContractType = DbContractType & { contract: any };
+export type FlatDbContractType = Omit<DbContractType, 'contract' | 'latestUpdate'> &
+    Partial<Record<`contract.${string}`, string | boolean>> & {
+        latestUpdate?: string;
+    };
 
 export const DbTransactionValidator = z.object({
     id: z.string(),
@@ -73,6 +110,10 @@ export const DbTermsValidator = z.object({
     mutationVersion: z.coerce.number().int().nonnegative().optional(),
     id: z.string(),
     status: ConsentFlowTermsStatusValidator,
+    consentedVersion: z.coerce.number().int().positive().optional(),
+    lastReviewedVersion: z.coerce.number().int().positive().optional(),
+    reconsentDeadline: z.string().optional(),
+    newOptionsUntil: z.string().optional(),
     // Neo4j has no properties to store for entirely empty permission objects.
     terms: ConsentFlowTermsValidator.prefault({}),
     guardianApproval: ConsentFlowGuardianApprovalValidator.optional(),

package/src/types/credential-refresh.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 
 import {
     CredentialRefreshSigningModeValidator,
+    CredentialRefreshUpdateReasonValidator,
     PublishCredentialRefreshNotificationValidator,
 } from '@learncard/types';
 
@@ -45,6 +46,12 @@ export const CredentialRefreshRecordValidator = z.object({
     rootMaterialDigest: z.string().optional(),
     /** Server-keyed fingerprint of the original credentialStatus descriptor */
     credentialStatusDigest: z.string().optional(),
+    /** Exact public status descriptor, including object/array shape. JSON null means absent. */
+    credentialStatusBinding: z.string().optional(),
+    /** Exact signed refresh-service descriptor, including additional services and array order. */
+    refreshServiceBinding: z.string().optional(),
+    encryptionMode: z.enum(['network', 'holder']).optional(),
+    statusEntries: z.string().optional(),
     /** Keyed fingerprint of version 1 subject identifiers; no extra subject DIDs persisted. */
     credentialSubjectDigest: z.string().optional(),
     /** Optional boost permanently associated with the initial credential bind. */
@@ -54,6 +61,7 @@ export const CredentialRefreshRecordValidator = z.object({
     idempotencyKey: z.string().optional(),
     /** Issuer-authored, privacy-safe update summary */
     updateSummary: z.string().optional(),
+    updateReason: CredentialRefreshUpdateReasonValidator.optional(),
     /**
      * Bounded, normalized credential display title used only for the email update
      * notice. Never rendered in in-app/push payloads. Sourced from the unsigned
@@ -108,6 +116,7 @@ export const CredentialRefreshVersionNodeValidator = z.object({
     etag: z.string().optional(),
     signingMode: CredentialRefreshSigningModeValidator,
     updateSummary: z.string().optional(),
+    updateReason: CredentialRefreshUpdateReasonValidator.optional(),
     /** Bounded credential display title for the email update notice only. */
     credentialDisplayName: z.string().optional(),
     /** Caller-provided key for replaying this exact historical publication */
@@ -148,7 +157,8 @@ export const AdvanceCredentialRefreshHeadParamsValidator = z.object({
     etag: z.string().optional(),
     materialDigest: z.string().optional(),
     signingMode: CredentialRefreshSigningModeValidator,
-    updateSummary: z.string().optional(),
+    updateSummary: z.string().max(280).optional(),
+    updateReason: CredentialRefreshUpdateReasonValidator.optional(),
     /** Bounded credential display title persisted for the email update notice only. */
     credentialDisplayName: z.string().optional(),
     idempotencyKey: z.string().optional(),

package/src/types/credential.ts

@@ -12,5 +12,7 @@ export const CredentialValidator = z.object({
     id: z.string(),
     credential: z.string(),
     statusEntries: z.string().optional(),
+    statusOwnerProfileId: z.string().optional(),
+    statusReservationMode: z.enum(['strict', 'lenient']).optional(),
 });
 export type CredentialType = z.infer<typeof CredentialValidator>;