@learncard/network-plugin 3.2.3 → 4.0.0

package/src/test/index.test.ts

@@ -360,6 +360,45 @@ describe('connection prompt methods', () => {
     });
 });
 
+describe('updateContract patch shapes', () => {
+    beforeEach(() => vi.clearAllMocks());
+
+    it.each(['read', 'write'] as const)(
+        'rejects overlapping %s patches without a server mutation',
+        async area => {
+            const mutate = vi.fn();
+            const client = {
+                ...getMockClient(),
+                contracts: { updateConsentFlowContract: { mutate } },
+            };
+            vi.mocked(getBrainClient).mockResolvedValue(client as never);
+            const learnCard = getMockLearnCard();
+            const plugin = await getLearnCardNetworkPlugin(
+                learnCard,
+                'https://network.example/trpc'
+            );
+
+            await expect(
+                plugin.methods?.updateContract(learnCard, 'contract:1', {
+                    [area]: {
+                        credentials: { categories: { Transcript: { required: true } } },
+                        personal: {},
+                    },
+                    contract: {
+                        [area]: {
+                            credentials: { categories: { Certificate: { required: true } } },
+                            personal: {},
+                        },
+                    },
+                })
+            ).rejects.toThrow(
+                'Contract read/write updates must use either the top-level or nested contract shape'
+            );
+            expect(mutate).not.toHaveBeenCalled();
+        }
+    );
+});
+
 describe('credential refresh methods', () => {
     beforeEach(() => {
         vi.clearAllMocks();
@@ -613,6 +652,38 @@ describe('credential refresh methods', () => {
         expect(client.utilities.getDid.query).not.toHaveBeenCalled();
     });
 
+    it('sendBoost throws instead of signing when the boost is a display-only anchor', async () => {
+        const client = getMockClient();
+        client.boost.getBoost.query.mockResolvedValue({
+            boost: getUnsignedBoostTemplate({ displayOnlyAnchor: true, display: {} }),
+        });
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const { learnCard } = getMockIssuingLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+
+        await expect(
+            plugin.methods?.sendBoost(learnCard, 'userb', 'did:example:boost:1')
+        ).rejects.toThrow('display-only anchor');
+
+        expect(learnCard.invoke.issueCredential).not.toHaveBeenCalled();
+    });
+
+    it('sendBoost signs normally when the boost has its own display object (not a display-only anchor)', async () => {
+        const client = getMockClient();
+        client.boost.getBoost.query.mockResolvedValue({
+            boost: getUnsignedBoostTemplate({
+                display: { backgroundColor: '#fff', backgroundImage: '', displayType: 'card' },
+            }),
+        });
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const { learnCard } = getMockIssuingLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+
+        await plugin.methods?.sendBoost(learnCard, 'userb', 'did:example:boost:1');
+
+        expect(learnCard.invoke.issueCredential).toHaveBeenCalled();
+    });
+
     it('sendBoost receipt preserves the exact credentialStatus descriptor from the signed VC', async () => {
         const client = getMockClient();
         vi.mocked(getBrainClient).mockResolvedValue(client as never);

package/src/test/refresh-send.test.ts

@@ -43,6 +43,8 @@ vi.mock('@learncard/types', async importOriginal => ({
         },
     },
     UnsignedVCValidator: {
+        parse: (await importOriginal<typeof import('@learncard/types')>()).UnsignedVCValidator
+            .parse,
         spa: async (value: any) => ({
             success: true,
             data: typeof value === 'string' ? JSON.parse(value) : value,
@@ -174,6 +176,56 @@ const getPlugin = async (learnCard: any, client: any) => {
 };
 
 describe('unified send with refresh: true (managed branch)', () => {
+    it('includes revocation when an old server requires fallback suspension allocation', async () => {
+        const client = getMockClient();
+        const learnCard = getMockIssuingLearnCard();
+        const plugin = await getPlugin(learnCard, client);
+        await plugin.methods?.send(learnCard, {
+            type: 'boost',
+            recipient: 'userb',
+            templateUri: 'did:web:network.example:boost:1',
+            refresh: true,
+            statusPurposes: ['suspension'],
+        });
+        expect(client.boost.allocateCredentialStatus.mutate).toHaveBeenCalledWith({
+            statusPurposes: ['revocation', 'suspension'],
+        });
+    });
+
+    it.each([false, true])(
+        'uses server-bound status without allocating again (array=%s)',
+        async arrayShape => {
+            const client = getMockClient();
+            const learnCard = getMockIssuingLearnCard();
+            const entry = SERVER_MANAGED_RESPONSE.refresh.credentialStatus;
+            client.boost.prepareRefreshableSend.mutate.mockResolvedValue(
+                Object.assign(
+                    {},
+                    {
+                        ...defaultPrepared,
+                        statusEntries: [entry],
+                    }
+                )
+            );
+            client.boost.getBoost.query.mockResolvedValue({
+                boost: getUnsignedBoostTemplate({ credentialStatus: arrayShape ? [entry] : entry }),
+            });
+            const plugin = await getPlugin(learnCard, client);
+            await plugin.methods?.send(learnCard, {
+                type: 'boost',
+                recipient: 'userb',
+                templateUri: 'did:web:network.example:boost:1',
+                refresh: true,
+            });
+            expect(client.boost.allocateCredentialStatus.mutate).not.toHaveBeenCalled();
+            expect(learnCard.invoke.issueCredential).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    credentialStatus: arrayShape ? [entry] : entry,
+                })
+            );
+        }
+    );
+
     beforeEach(() => {
         vi.clearAllMocks();
     });
@@ -219,9 +271,10 @@ describe('unified send with refresh: true (managed branch)', () => {
         // The server runs every guard, creates/reuses the boost and allocates the
         // refresh in one call; the SDK never allocates client-side.
         expect(client.boost.prepareRefreshableSend.mutate).toHaveBeenCalledExactlyOnceWith({
+            statusBinding: 'server',
             recipient: 'userb',
             templateUri: 'did:web:network.example:boost:1',
-            templateData: { name: 'Refreshable Badge' },
+            display: undefined,
         });
         expect(client.credentialRefresh.allocateCredentialRefresh.mutate).not.toHaveBeenCalled();
 
@@ -249,6 +302,47 @@ describe('unified send with refresh: true (managed branch)', () => {
         expect(learnCard.invoke.createDagJwe).not.toHaveBeenCalled();
     });
 
+    it('throws instead of signing when templateUri points at a display-only anchor', async () => {
+        const client = getMockClient();
+        const learnCard = getMockIssuingLearnCard();
+        client.boost.getBoost.query.mockResolvedValue({
+            boost: getUnsignedBoostTemplate({ displayOnlyAnchor: true, display: {} }),
+        });
+        const plugin = await getPlugin(learnCard, client);
+
+        await expect(
+            plugin.methods?.send(learnCard, {
+                type: 'boost',
+                recipient: 'userb',
+                templateUri: 'did:web:network.example:boost:1',
+                refresh: true,
+            })
+        ).rejects.toThrow('display-only anchor');
+
+        expect(learnCard.invoke.issueCredential).not.toHaveBeenCalled();
+        expect(client.boost.prepareRefreshableSend.mutate).not.toHaveBeenCalled();
+    });
+
+    it('signs normally from templateUri when the Boost has its own display object (not a display-only anchor)', async () => {
+        const client = getMockClient();
+        const learnCard = getMockIssuingLearnCard();
+        client.boost.getBoost.query.mockResolvedValue({
+            boost: getUnsignedBoostTemplate({
+                display: { backgroundColor: '#fff', backgroundImage: '', displayType: 'card' },
+            }),
+        });
+        const plugin = await getPlugin(learnCard, client);
+
+        await plugin.methods?.send(learnCard, {
+            type: 'boost',
+            recipient: 'userb',
+            templateUri: 'did:web:network.example:boost:1',
+            refresh: true,
+        });
+
+        expect(learnCard.invoke.issueCredential).toHaveBeenCalled();
+    });
+
     it('prepares the inline boost before signing and reuses its prepared URI for delivery', async () => {
         const client = getMockClient();
         const learnCard = getMockIssuingLearnCard();
@@ -272,8 +366,10 @@ describe('unified send with refresh: true (managed branch)', () => {
         const forwarded = client.boost.send.mutate.mock.calls[0]?.[0] as any;
 
         expect(client.boost.prepareRefreshableSend.mutate).toHaveBeenCalledExactlyOnceWith({
+            statusBinding: 'server',
             recipient: 'userb',
-            template,
+            templateUri: undefined,
+            display: undefined,
             contractUri: 'contract:1',
             credentialId: 'urn:uuid:inline-credential-id',
         });
@@ -297,6 +393,34 @@ describe('unified send with refresh: true (managed branch)', () => {
         expect(client.credentialRefresh.sendRefreshableCredential.mutate).not.toHaveBeenCalled();
     });
 
+    it('preserves inline external status without requesting server binding or allocating indexes', async () => {
+        const client = getMockClient();
+        const learnCard = getMockIssuingLearnCard();
+        const plugin = await getPlugin(learnCard, client);
+        const credentialStatus = {
+            ...SERVER_MANAGED_RESPONSE.refresh.credentialStatus,
+            id: 'https://provider.example/list#94567',
+            statusListCredential: 'https://provider.example/list',
+        };
+        const response = { ...SERVER_MANAGED_RESPONSE, statusManagement: 'external' as const };
+        client.boost.send.mutate.mockResolvedValue(response);
+        const result = await plugin.methods?.send(learnCard, {
+            type: 'boost',
+            recipient: 'userb',
+            template: { credential: getUnsignedBoostTemplate({ credentialStatus }) },
+            refresh: true,
+            statusPurposes: ['suspension'],
+        });
+        expect(client.boost.prepareRefreshableSend.mutate.mock.calls[0]?.[0]).not.toHaveProperty(
+            'statusBinding'
+        );
+        expect(client.boost.allocateCredentialStatus.mutate).not.toHaveBeenCalled();
+        expect(learnCard.invoke.issueCredential).toHaveBeenCalledWith(
+            expect.objectContaining({ credentialStatus })
+        );
+        expect(result).toEqual(response);
+    });
+
     it('signs with the prepared credential ID, refresh service and holder DID', async () => {
         const client = getMockClient();
         const learnCard = getMockIssuingLearnCard();
@@ -420,7 +544,7 @@ describe('unified send with refresh: true (managed branch)', () => {
         expect(forwarded.signedCredential.credentialSubject.id).toEqual(defaultPrepared.holderDid);
     });
 
-    it('includes claim data and integration in the keyed preparation fingerprint', async () => {
+    it('includes public integration metadata but not claim data in preparation', async () => {
         const client = getMockClient();
         const learnCard = getMockIssuingLearnCard();
         const plugin = await getPlugin(learnCard, client);
@@ -435,11 +559,13 @@ describe('unified send with refresh: true (managed branch)', () => {
         });
         expect(client.boost.prepareRefreshableSend.mutate).toHaveBeenCalledWith(
             expect.objectContaining({
-                templateData: { grade: 'A' },
                 integrationId: 'integration-1',
                 idempotencyKey: 'award-1',
             })
         );
+        expect(client.boost.prepareRefreshableSend.mutate.mock.calls[0]?.[0]).not.toHaveProperty(
+            'templateData'
+        );
     });
 
     it('delegates unchanged to the server signing-authority path when local signing is unavailable', async () => {
@@ -463,6 +589,25 @@ describe('unified send with refresh: true (managed branch)', () => {
         expect(learnCard.invoke.issueCredential).toBeUndefined();
     });
 
+    it('forwards statusPurposes to the server signing-authority path when local signing is unavailable', async () => {
+        const client = getMockClient();
+        const learnCard = getMockIssuingLearnCard();
+        delete learnCard.invoke.issueCredential;
+        const plugin = await getPlugin(learnCard, client);
+
+        await plugin.methods?.send(learnCard, {
+            type: 'boost',
+            recipient: 'userb',
+            templateUri: 'did:web:network.example:boost:1',
+            refresh: true,
+            statusPurposes: ['suspension'],
+        });
+
+        expect(client.boost.send.mutate).toHaveBeenCalledWith(
+            expect.objectContaining({ statusPurposes: ['suspension'] })
+        );
+    });
+
     it.each([
         {},
         { templateUri: 'did:web:network.example:boost:1' },

package/src/types.ts

@@ -1,10 +1,14 @@
+import type { CampaignAudienceResult } from '@learncard/types';
 import type { SendContractRequest, ConsentFlowContractRequestForProfile } from '@learncard/types';
 import type { LCNClient } from '@learncard/network-brain-client';
 import type {
     Campaign,
     CampaignAudienceInput,
+    AnnouncementPreferences,
     CampaignEvent,
     CampaignStats,
+    CampaignDispatchPreview,
+    CampaignDispatchOptions,
     CampaignStatus,
     CreateCampaignInput,
     UpdateCampaignInput,
@@ -14,6 +18,10 @@ import type {
     PaginatedCampaigns,
     PaginatedCampaignAudience,
     PublishCredentialSharePreview,
+    ConsentFlowContractChanges,
+    ConsentFlowContractUpdateResult,
+    ConsentFlowContractVersion,
+    ConsentFlowConsentStatus,
 } from '@learncard/types';
 import {
     LCNProfile,
@@ -80,7 +88,6 @@ import {
     PaginatedConsentFlowDataForDid,
     PaginatedContractCredentials,
     AutoBoostConfig,
-    SendInput,
     SendResponse,
     AuthGrantType,
     AuthGrantQuery,
@@ -155,7 +162,11 @@ import {
     PublishCredentialRefreshInput,
     PublishCredentialRefreshResult,
     GetCredentialRefreshHistoryInput,
+    type GetCredentialRefreshReceiptInput,
+    type CredentialRefreshReceipt,
     GetCredentialRefreshHistoryResult,
+    type SendBoostInput,
+    type CredentialRefreshUpdateReason,
 } from '@learncard/types';
 import { LearnCard, Plugin } from '@learncard/core';
 import { ProofOptions } from '@learncard/didkit-plugin';
@@ -213,6 +224,32 @@ export type SendBoostResultFor<Options> = [EnableRefreshOf<Options>] extends [tr
       ? string | SendBoostRefreshResult
       : string;
 
+/**
+ * `send` input extended with the LC-2345 holder-mode `encryption` field. A local
+ * intersection rather than a `@learncard/types` edit, because today the field is
+ * validated and enforced entirely client-side (rejected for inbox recipients,
+ * `signedCredential`, and servers that don't return `recipientKeyIds`).
+ */
+export type SendBoostInputWithEncryption = SendBoostInput & {
+    /**
+     * `'holder'` requests student-only encryption: the SDK signs and encrypts
+     * locally so the server never receives plaintext. Requires `refresh: true` and a
+     * profile or DID recipient. Defaults to `'network'`.
+     */
+    encryption?: 'network' | 'holder';
+};
+
+/** Options for {@link LearnCardNetworkPluginMethods.publishHolderEncryptedRefreshable}. */
+export type PublishHolderEncryptedRefreshableOptions = {
+    /** Applied locally with the same templating `send` uses; never sent to the server. */
+    templateData?: Record<string, unknown>;
+    /** Replaces server-inferred materiality: the server cannot compare encrypted content across versions. */
+    notify: boolean;
+    updateSummary?: string;
+    updateReason?: CredentialRefreshUpdateReason;
+    idempotencyKey?: string;
+};
+
 /** @group LearnCardNetwork Plugin */
 export type LearnCardNetworkPluginDependentMethods = {
     getDidAuthVp: (options?: ProofOptions) => Promise<VP | string>;
@@ -222,6 +259,8 @@ export type LearnCardNetworkPluginDependentMethods = {
     ) => Promise<VC>;
     clearDidWebCache?: () => Promise<void>;
     createDagJwe: (cleartext: any, recipients: string[]) => Promise<JWE>;
+    /** Encrypts only to explicit recipients, without adding the caller. */
+    createDagJweExact?: <T>(cleartext: T, recipients: string[]) => Promise<JWE>;
     decryptDagJwe: (jwe: JWE, jwks: any[]) => Promise<any>;
     resolveDid: (did: string) => Promise<DidDocument>;
 };
@@ -611,6 +650,17 @@ export type LearnCardNetworkPluginMethods = {
     publishCredentialRefresh: (
         input: PublishCredentialRefreshInput
     ) => Promise<PublishCredentialRefreshResult>;
+    /**
+     * Holder-mode (LC-2345) counterpart of `publishCredentialRefresh`: builds and
+     * signs a new version locally from `receipt`'s bindings, encrypts it exactly to
+     * the current holder + manager recipients, and sends only the ciphertext
+     * handoff. Rejects when local signing is unavailable.
+     */
+    publishHolderEncryptedRefreshable: (
+        receipt: ManagedCredentialRefreshReceipt,
+        credential: UnsignedVC,
+        options: PublishHolderEncryptedRefreshableOptions
+    ) => Promise<PublishCredentialRefreshResult>;
     /**
      * Cursor-paginated, metadata-only issuer audit history for a managed refresh.
      * Never includes credential bodies or encrypted payloads.
@@ -618,6 +668,10 @@ export type LearnCardNetworkPluginMethods = {
     getCredentialRefreshHistory: (
         input: GetCredentialRefreshHistoryInput
     ) => Promise<GetCredentialRefreshHistoryResult>;
+    /** Read the authenticated public binding for a pending managed delivery. */
+    getCredentialRefreshReceipt: (
+        input: GetCredentialRefreshReceiptInput
+    ) => Promise<CredentialRefreshReceipt | null>;
     revokeBoostRecipient: (
         boostUri: string,
         recipientProfileId: string,
@@ -668,10 +722,14 @@ export type LearnCardNetworkPluginMethods = {
     ) => Promise<{ boostUri: string; challenge: string }>;
     claimBoostWithLink: (boostUri: string, challenge: string) => Promise<string>;
 
-    send: (input: SendInput) => Promise<SendResponse>;
+    send: (input: SendBoostInputWithEncryption) => Promise<SendResponse>;
 
     createContract: (contract: {
         contract: ConsentFlowContract;
+        reasonForAccessing?: string;
+        needsGuardianConsent?: boolean;
+        redirectUrl?: string;
+        frontDoorBoostUri?: string;
         name: string;
         subtitle?: string;
         description?: string;
@@ -681,14 +739,42 @@ export type LearnCardNetworkPluginMethods = {
         recipients?: string[];
         autoboosts?: AutoBoostConfig[];
     }) => Promise<string>;
-    addAutoBoostsToContract: (
-        contractUri: string,
-        autoboosts: AutoBoostConfig[]
-    ) => Promise<boolean>;
-    removeAutoBoostsFromContract: (contractUri: string, boostUris: string[]) => Promise<boolean>;
+    /**
+     * Updates a live request at the same URI, or previews it without saving.
+     * Scope maps merge with the current request. Set an entry to null to remove it;
+     * expiresAt: null clears expiry. AutoBoost and writer arrays replace their lists.
+     * Pass expectedVersion from the original draft to reject intervening publications.
+     * @example
+     * await learnCard.invoke.updateContract(uri, {
+     *     read: { credentials: { categories: {
+     *         Transcript: { required: true, reason: 'to calculate your GPA' },
+     *     } } },
+     * }, { reason: 'We added transcripts so we can show your GPA on your résumé.' });
+     */
+    updateContract: (
+        uri: string,
+        changes: ConsentFlowContractChanges & NonNullable<ConsentFlowContractChanges['contract']>,
+        options?: {
+            reason?: string;
+            reconsentDeadline?: string;
+            dryRun?: boolean;
+            expectedVersion?: number;
+        }
+    ) => Promise<ConsentFlowContractUpdateResult>;
     addContractRecipient: (contractUri: string, recipient: string) => Promise<boolean>;
     removeContractRecipient: (contractUri: string, recipient: string) => Promise<boolean>;
+    /** Gets the current request, including its version.
+     * @example const contract = await learnCard.invoke.getContract(uri);
+     */
     getContract: (uri: string) => Promise<ConsentFlowContractDetails>;
+    /** Lists a request's saved versions, newest first.
+     * @example const versions = await learnCard.invoke.getContractVersions(uri);
+     */
+    getContractVersions: (uri: string) => Promise<ConsentFlowContractVersion[]>;
+    /** Checks a user's access state and provides a review link when approval is needed.
+     * @example const { needsReconsent, reviewUrl } = await learnCard.invoke.getConsentStatus(uri, profileId);
+     */
+    getConsentStatus: (uri: string, profileId: string) => Promise<ConsentFlowConsentStatus>;
     getContracts: (
         options?: Partial<PaginationOptionsType> & { query?: ConsentFlowContractQuery }
     ) => Promise<PaginatedConsentFlowContracts>;
@@ -736,6 +822,13 @@ export type LearnCardNetworkPluginMethods = {
             audienceVersion?: number;
         }
     ) => Promise<boolean>;
+    /** Accepts the reviewed update using the user's selected data.
+     * @example await learnCard.invoke.acceptContractUpdate(termsUri, { version: 2, terms, audienceVersion: currentContract.audienceVersion });
+     */
+    acceptContractUpdate: (
+        termsUri: string,
+        update: { version: number; terms: ConsentFlowTerms; audienceVersion?: number }
+    ) => Promise<boolean>;
     withdrawConsent: (uri: string) => Promise<boolean>;
     getConsentFlowTransactions: (
         uri: string,
@@ -1130,6 +1223,11 @@ export type LearnCardNetworkPluginMethods = {
     }>;
 
     isAppStoreAdmin: () => Promise<boolean>;
+    getAnnouncementPreferences: () => Promise<AnnouncementPreferences>;
+    updateAnnouncementPreferences: (
+        updates: Partial<AnnouncementPreferences>
+    ) => Promise<AnnouncementPreferences>;
+    unsubscribeFromAnnouncements: (token: string) => Promise<boolean>;
     campaignsIsAdmin: () => Promise<boolean>;
     campaignsCreate: (input: CreateCampaignInput) => Promise<Campaign>;
     campaignsUpdate: (input: UpdateCampaignInput) => Promise<Campaign>;
@@ -1137,12 +1235,26 @@ export type LearnCardNetworkPluginMethods = {
     campaignsList: (input?: ListCampaignsInput) => Promise<PaginatedCampaigns>;
     campaignsDelete: (campaignId: string) => Promise<boolean>;
     campaignsSetStatus: (campaignId: string, status: CampaignStatus) => Promise<Campaign>;
-    campaignsPreviewAudience: (input: CampaignAudienceInput) => Promise<{ count: number }>;
-    campaignsAddAudience: (input: CampaignAudienceInput) => Promise<{ count: number }>;
+    campaignsPreviewAudience: (input: CampaignAudienceInput) => Promise<CampaignAudienceResult>;
+    campaignsAddAudience: (input: CampaignAudienceInput) => Promise<CampaignAudienceResult>;
     campaignsPageAudience: (input: PageCampaignAudienceInput) => Promise<PaginatedCampaignAudience>;
     campaignsGetStats: (campaignId: string) => Promise<CampaignStats>;
+    /** Test selected channels only for the signed-in administrator, regardless of campaign status. */
+    campaignsSendTestToMe: (campaignId: string) => Promise<boolean>;
+    /** Start paced notification delivery for an eligible live campaign. */
+    /** Preview eligible inbox recipients before confirming an audience notification send. */
+    campaignsPreviewDispatch: (campaignId: string) => Promise<CampaignDispatchPreview>;
+    /** Supply the preview token to reject stale or repeated confirmations. */
+    campaignsDispatch: (
+        campaignId: string,
+        options?: CampaignDispatchOptions
+    ) => Promise<{ dispatchId: string }>;
     getMyCampaigns: () => Promise<MyCampaign[]>;
-    recordCampaignEvent: (campaignId: string, event: CampaignEvent) => Promise<boolean>;
+    recordCampaignEvent: (
+        campaignId: string,
+        event: CampaignEvent,
+        testId?: string
+    ) => Promise<boolean>;
     enrollInCampaign: (campaignId: string) => Promise<boolean>;
     adminUpdateListingStatus: (listingId: string, status: AppListingStatus) => Promise<boolean>;
     adminUpdatePromotionLevel: (