@learncard/network-plugin 2.14.0 → 3.0.0

package/src/test/act-as.test.ts

@@ -0,0 +1,323 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- plugin integration mocks intentionally expose dynamic method bags */
+import { getClient as getBrainClient, getApiTokenClient } from '@learncard/network-brain-client';
+import { vi } from 'vitest';
+
+import { ACT_AS_HEADER, getLearnCardNetworkPlugin } from '../plugin';
+
+vi.mock('@learncard/network-brain-client', () => ({
+    getClient: vi.fn(),
+    getApiTokenClient: vi.fn(),
+}));
+
+const PROFILE = {
+    profileId: 'usera',
+    displayName: 'User A',
+    shortBio: '',
+    bio: '',
+    did: 'did:web:network.example:users:usera',
+    isPrivate: false,
+    profileVisibility: 'public',
+    showEmail: false,
+    allowConnectionRequests: 'anyone',
+    isServiceProfile: false,
+};
+
+const URL = 'https://network.example/trpc';
+
+const getMockClient = () => ({
+    profile: { getProfile: { query: vi.fn().mockResolvedValue(PROFILE) } },
+});
+
+const getMockLearnCard = () => {
+    const learnCard: any = {
+        plugins: [],
+        id: { did: () => PROFILE.did },
+        invoke: { getDidAuthVp: vi.fn().mockResolvedValue('mock-jwt') },
+        debug: vi.fn(),
+    };
+    learnCard.addPlugin = vi.fn(async (plugin: any) => ({
+        ...learnCard,
+        plugins: [...learnCard.plugins, plugin],
+    }));
+
+    return learnCard;
+};
+
+describe('actAs', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    describe('extraHeaders wiring', () => {
+        it('omits the act-as header for the API-token client when actAs is not set', async () => {
+            vi.mocked(getApiTokenClient).mockResolvedValue(getMockClient() as never);
+            const learnCard = getMockLearnCard();
+
+            await getLearnCardNetworkPlugin(learnCard, URL, 'api-token-value');
+
+            expect(getApiTokenClient).toHaveBeenCalledWith(
+                URL,
+                'api-token-value',
+                undefined,
+                undefined
+            );
+        });
+
+        it('adds the act-as header for the API-token client when actAs is set', async () => {
+            vi.mocked(getApiTokenClient).mockResolvedValue(getMockClient() as never);
+            const learnCard = getMockLearnCard();
+
+            await getLearnCardNetworkPlugin(learnCard, URL, 'api-token-value', {
+                actAs: 'managed-child',
+            });
+
+            expect(getApiTokenClient).toHaveBeenCalledWith(URL, 'api-token-value', undefined, {
+                [ACT_AS_HEADER]: 'managed-child',
+            });
+        });
+
+        it('merges the act-as header alongside other extraHeaders', async () => {
+            vi.mocked(getApiTokenClient).mockResolvedValue(getMockClient() as never);
+            const learnCard = getMockLearnCard();
+
+            await getLearnCardNetworkPlugin(learnCard, URL, 'api-token-value', {
+                actAs: 'managed-child',
+                extraHeaders: { 'X-Custom': '1' },
+            });
+
+            expect(getApiTokenClient).toHaveBeenCalledWith(URL, 'api-token-value', undefined, {
+                'X-Custom': '1',
+                [ACT_AS_HEADER]: 'managed-child',
+            });
+        });
+
+        it('omits the act-as header for the seed/DID-auth client when actAs is not set', async () => {
+            vi.mocked(getBrainClient).mockResolvedValue(getMockClient() as never);
+            const learnCard = getMockLearnCard();
+
+            await getLearnCardNetworkPlugin(learnCard, URL);
+
+            expect(getBrainClient).toHaveBeenCalledWith(
+                URL,
+                expect.any(Function),
+                undefined,
+                undefined
+            );
+        });
+
+        it('adds the act-as header for the seed/DID-auth client when actAs is set', async () => {
+            vi.mocked(getBrainClient).mockResolvedValue(getMockClient() as never);
+            const learnCard = getMockLearnCard();
+
+            await getLearnCardNetworkPlugin(learnCard, URL, { actAs: 'managed-child' });
+
+            expect(getBrainClient).toHaveBeenCalledWith(URL, expect.any(Function), undefined, {
+                [ACT_AS_HEADER]: 'managed-child',
+            });
+        });
+    });
+
+    describe('.actAs(profileId) method', () => {
+        it('api-token mode: returns a new LearnCard carrying the header, without mutating the original', async () => {
+            const originalClient = getMockClient();
+            const actingClient = getMockClient();
+            vi.mocked(getApiTokenClient)
+                .mockResolvedValueOnce(originalClient as never)
+                .mockResolvedValueOnce(actingClient as never);
+
+            const learnCard = getMockLearnCard();
+            const plugin = await getLearnCardNetworkPlugin(learnCard, URL, 'api-token-value');
+
+            expect(plugin.methods.getLCNClient(learnCard)).toBe(originalClient);
+
+            const newLearnCard = await plugin.methods.actAs(learnCard, 'managed-child');
+
+            expect(getApiTokenClient).toHaveBeenNthCalledWith(
+                2,
+                URL,
+                'api-token-value',
+                undefined,
+                {
+                    [ACT_AS_HEADER]: 'managed-child',
+                }
+            );
+            expect(learnCard.addPlugin).toHaveBeenCalledTimes(1);
+
+            const [actingPlugin] = vi.mocked(learnCard.addPlugin).mock.calls[0] as [any];
+            expect(actingPlugin.name).toBe('LearnCard Network');
+            expect(actingPlugin.methods.getLCNClient(learnCard)).toBe(actingClient);
+
+            // The original instance/plugin must be untouched by the .actAs call.
+            expect(newLearnCard).not.toBe(learnCard);
+            expect(learnCard.plugins).toEqual([]);
+            expect(plugin.methods.getLCNClient(learnCard)).toBe(originalClient);
+        });
+
+        it('seed/DID-auth mode: returns a new LearnCard carrying the header, without mutating the original', async () => {
+            const originalClient = getMockClient();
+            const actingClient = getMockClient();
+            vi.mocked(getBrainClient)
+                .mockResolvedValueOnce(originalClient as never)
+                .mockResolvedValueOnce(actingClient as never);
+
+            const learnCard = getMockLearnCard();
+            const plugin = await getLearnCardNetworkPlugin(learnCard, URL);
+
+            expect(plugin.methods.getLCNClient(learnCard)).toBe(originalClient);
+
+            await plugin.methods.actAs(learnCard, 'managed-child');
+
+            expect(getBrainClient).toHaveBeenNthCalledWith(
+                2,
+                URL,
+                expect.any(Function),
+                undefined,
+                {
+                    [ACT_AS_HEADER]: 'managed-child',
+                }
+            );
+
+            const [actingPlugin] = vi.mocked(learnCard.addPlugin).mock.calls[0] as [any];
+            expect(actingPlugin.methods.getLCNClient(learnCard)).toBe(actingClient);
+
+            // Original plugin's client reference is unaffected.
+            expect(plugin.methods.getLCNClient(learnCard)).toBe(originalClient);
+        });
+
+        it('preserves pre-existing extraHeaders and federation options when composing the acting plugin', async () => {
+            vi.mocked(getApiTokenClient)
+                .mockResolvedValueOnce(getMockClient() as never)
+                .mockResolvedValueOnce(getMockClient() as never);
+
+            const learnCard = getMockLearnCard();
+            const plugin = await getLearnCardNetworkPlugin(learnCard, URL, 'api-token-value', {
+                extraHeaders: { 'X-Custom': '1' },
+                trustedFederationHosts: ['trusted.example'],
+            });
+
+            await plugin.methods.actAs(learnCard, 'managed-child');
+
+            expect(getApiTokenClient).toHaveBeenNthCalledWith(
+                2,
+                URL,
+                'api-token-value',
+                undefined,
+                {
+                    'X-Custom': '1',
+                    [ACT_AS_HEADER]: 'managed-child',
+                }
+            );
+        });
+
+        it.each(['FORBIDDEN', 'BAD_REQUEST'])(
+            'rethrows a %s act-as denial, wrapping the original error as `cause`',
+            async code => {
+                const denial = Object.assign(new Error(`act-as ${code}`), { data: { code } });
+                const actingClient = {
+                    profile: { getProfile: { query: vi.fn().mockRejectedValue(denial) } },
+                };
+                vi.mocked(getApiTokenClient)
+                    .mockResolvedValueOnce(getMockClient() as never)
+                    .mockResolvedValueOnce(actingClient as never);
+
+                const learnCard = getMockLearnCard();
+                const plugin = await getLearnCardNetworkPlugin(learnCard, URL, 'api-token-value');
+
+                const rejection: any = await plugin.methods
+                    .actAs(learnCard, 'not-mine')
+                    .catch(e => e);
+                expect(rejection).toBeInstanceOf(Error);
+                expect(rejection.cause).toBe(denial);
+                expect(learnCard.addPlugin).not.toHaveBeenCalled();
+            }
+        );
+
+        it('rethrows a NOT_FOUND act-as denial when the message matches resolveActAs', async () => {
+            const denial = Object.assign(new Error('Act-as target profile not found'), {
+                data: { code: 'NOT_FOUND' },
+            });
+            const actingClient = {
+                profile: { getProfile: { query: vi.fn().mockRejectedValue(denial) } },
+            };
+            vi.mocked(getApiTokenClient)
+                .mockResolvedValueOnce(getMockClient() as never)
+                .mockResolvedValueOnce(actingClient as never);
+
+            const learnCard = getMockLearnCard();
+            const plugin = await getLearnCardNetworkPlugin(learnCard, URL, 'api-token-value');
+
+            const rejection: any = await plugin.methods.actAs(learnCard, 'not-mine').catch(e => e);
+            expect(rejection).toBeInstanceOf(Error);
+            expect(rejection.cause).toBe(denial);
+            expect(learnCard.addPlugin).not.toHaveBeenCalled();
+        });
+
+        it('does not treat a NOT_FOUND with an unrelated message as an act-as denial', async () => {
+            const unrelated = Object.assign(
+                new Error('Profile not found. Please make a profile!'),
+                { data: { code: 'NOT_FOUND' } }
+            );
+            const actingClient = {
+                profile: { getProfile: { query: vi.fn().mockRejectedValue(unrelated) } },
+            };
+            vi.mocked(getApiTokenClient)
+                .mockResolvedValueOnce(getMockClient() as never)
+                .mockResolvedValueOnce(actingClient as never);
+
+            const learnCard = getMockLearnCard();
+            const plugin = await getLearnCardNetworkPlugin(learnCard, URL, 'api-token-value');
+
+            await expect(plugin.methods.actAs(learnCard, 'managed-child')).resolves.toBeDefined();
+            expect(learnCard.addPlugin).toHaveBeenCalledTimes(1);
+            expect(learnCard.debug).toHaveBeenCalledWith(
+                'LCN actAs: getProfile failed (non-fatal)',
+                unrelated
+            );
+        });
+
+        it('does not treat an INTERNAL_SERVER_ERROR as an act-as denial', async () => {
+            const serverError = Object.assign(new Error('boom'), {
+                data: { code: 'INTERNAL_SERVER_ERROR' },
+            });
+            const actingClient = {
+                profile: { getProfile: { query: vi.fn().mockRejectedValue(serverError) } },
+            };
+            vi.mocked(getApiTokenClient)
+                .mockResolvedValueOnce(getMockClient() as never)
+                .mockResolvedValueOnce(actingClient as never);
+
+            const learnCard = getMockLearnCard();
+            const plugin = await getLearnCardNetworkPlugin(learnCard, URL, 'api-token-value');
+
+            await expect(plugin.methods.actAs(learnCard, 'managed-child')).resolves.toBeDefined();
+            expect(learnCard.addPlugin).toHaveBeenCalledTimes(1);
+            expect(learnCard.debug).toHaveBeenCalledWith(
+                'LCN actAs: getProfile failed (non-fatal)',
+                serverError
+            );
+        });
+
+        it('still returns an instance when the profile fetch fails for an unrelated reason', async () => {
+            const actingClient = {
+                profile: {
+                    getProfile: {
+                        query: vi.fn().mockRejectedValue(
+                            Object.assign(new Error('no scope'), {
+                                data: { code: 'UNAUTHORIZED' },
+                            })
+                        ),
+                    },
+                },
+            };
+            vi.mocked(getApiTokenClient)
+                .mockResolvedValueOnce(getMockClient() as never)
+                .mockResolvedValueOnce(actingClient as never);
+
+            const learnCard = getMockLearnCard();
+            const plugin = await getLearnCardNetworkPlugin(learnCard, URL, 'api-token-value');
+
+            await expect(plugin.methods.actAs(learnCard, 'managed-child')).resolves.toBeDefined();
+            expect(learnCard.addPlugin).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/src/test/index.test.ts

@@ -17,17 +17,13 @@ vi.mock('@learncard/core', () => ({ generateLearnCard: vi.fn() }));
 vi.mock('@learncard/didkit-plugin', () => ({ getDidKitPlugin: vi.fn() }));
 vi.mock('@learncard/didkey-plugin', () => ({ getDidKeyPlugin: vi.fn() }));
 vi.mock('@learncard/vc-plugin', () => ({ getVCPlugin: vi.fn() }));
-vi.mock('@learncard/helpers', () => ({
-    isVC2Format: (credential: any) => {
-        const contexts = credential?.['@context'];
-        const list = Array.isArray(contexts) ? contexts : [contexts];
-
-        return list.includes('https://www.w3.org/ns/credentials/v2');
-    },
+vi.mock('@learncard/helpers', async importOriginal => ({
+    ...(await importOriginal<typeof import('@learncard/helpers')>()),
     getCredentialStatusArray: () => [],
     resolveStorageReadResult: (value: any) => value,
 }));
-vi.mock('@learncard/types', () => ({
+vi.mock('@learncard/types', async importOriginal => ({
+    ...(await importOriginal<object>()),
     VCValidator: {
         parse: (value: any) => {
             if (!value?.type) throw new Error('Invalid credential');
@@ -184,6 +180,124 @@ const getLearnCard = async (seed = 'a'.repeat(64)) => {
     };
 };
 
+describe('inbox batch method', () => {
+    beforeEach(() => vi.clearAllMocks());
+
+    it('forwards configuration, keys and items to issueBatch and returns an acceptance receipt', async () => {
+        const response = {
+            batchId: 'batch-1',
+            status: 'QUEUED',
+            createdAt: '2026-09-17T00:00:00.000Z',
+        };
+        const mutate = vi.fn().mockResolvedValue(response);
+        const client = { ...getMockClient(), inbox: { issueBatch: { mutate } } };
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const learnCard = getMockLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+        const batch = {
+            configuration: { delivery: { suppress: true } },
+            items: [
+                {
+                    recipient: { type: 'email' as const, value: 'student@example.test' },
+                    templateUri: 'test-template',
+                    idempotencyKey: 'test-key',
+                },
+            ],
+        };
+        await expect(plugin.methods?.sendCredentialsViaInbox(learnCard, batch)).resolves.toEqual(
+            response
+        );
+        expect(mutate).toHaveBeenCalledExactlyOnceWith(batch);
+        await expect(
+            plugin.methods?.sendCredentialBatchViaInbox(learnCard, batch)
+        ).resolves.toEqual(response);
+        expect(mutate).toHaveBeenLastCalledWith(batch);
+        expect(client.profile.getProfile.query).toHaveBeenCalled();
+    });
+
+    it('submits once, persists the receipt, and waits for completion through the SDK', async () => {
+        const receipt = { batchId: 'batch-1', status: 'QUEUED', createdAt: '2026-09-17' };
+        const response = { ...receipt, done: true, status: 'COMPLETED', items: [] };
+        const mutate = vi.fn().mockResolvedValue(receipt);
+        let saved = false;
+        const query = vi.fn(async () => {
+            expect(saved).toBe(true);
+            return response;
+        });
+        const client = {
+            ...getMockClient(),
+            inbox: { issueBatch: { mutate }, getBatch: { query } },
+        };
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const learnCard = getMockLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+        const batch = {
+            items: [
+                {
+                    recipient: { type: 'email' as const, value: 'a@example.test' },
+                    templateUri: 'template',
+                },
+            ],
+        };
+        await expect(
+            plugin.methods?.sendCredentialsViaInboxAndWait(learnCard, batch, {
+                onSubmitted: async received => {
+                    expect(received).toEqual(receipt);
+                    await Promise.resolve();
+                    saved = true;
+                },
+            })
+        ).resolves.toEqual(response);
+        expect(mutate).toHaveBeenCalledTimes(1);
+        expect(query).toHaveBeenCalledWith(
+            { batchId: receipt.batchId },
+            { signal: expect.any(AbortSignal) }
+        );
+        await expect(
+            plugin.methods?.waitForInboxCredentialBatch(learnCard, receipt.batchId)
+        ).resolves.toEqual(response);
+        expect(mutate).toHaveBeenCalledTimes(1);
+
+        const controller = new AbortController();
+        controller.abort();
+        await expect(
+            plugin.methods?.sendCredentialsViaInboxAndWait(learnCard, batch, {
+                signal: controller.signal,
+            })
+        ).rejects.toMatchObject({ name: 'AbortError' });
+        expect(mutate).toHaveBeenCalledTimes(1);
+    });
+
+    it('polls the batch endpoint and preserves progress and item results', async () => {
+        const response = { batchId: 'batch-1', status: 'PROCESSING', items: [] };
+        const query = vi.fn().mockResolvedValue(response);
+        const client = { ...getMockClient(), inbox: { getBatch: { query } } };
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const learnCard = getMockLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+        await expect(
+            plugin.methods?.getInboxCredentialBatch(learnCard, 'batch-1')
+        ).resolves.toEqual(response);
+        expect(query).toHaveBeenCalledExactlyOnceWith({ batchId: 'batch-1' });
+        query.mockRejectedValueOnce(new Error('Not found'));
+        await expect(plugin.methods?.getInboxCredentialBatch(learnCard, 'missing')).rejects.toThrow(
+            'Not found'
+        );
+    });
+
+    it('does not submit a batch when the issuer profile is missing', async () => {
+        const mutate = vi.fn();
+        const client = { ...getMockClient(null), inbox: { issueBatch: { mutate } } };
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const learnCard = getMockLearnCard();
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+        await expect(
+            plugin.methods?.sendCredentialsViaInbox(learnCard, { items: [] })
+        ).rejects.toThrow();
+        expect(mutate).not.toHaveBeenCalled();
+    });
+});
+
 describe('connection prompt methods', () => {
     beforeEach(() => {
         vi.clearAllMocks();
@@ -434,12 +548,25 @@ describe('credential refresh methods', () => {
         const { learnCard, issuedCredentials } = getMockIssuingLearnCard();
         const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
 
-        const uri = await plugin.methods?.sendBoost(learnCard, 'userb', 'did:example:boost:1', {
+        const result = await plugin.methods?.sendBoost(learnCard, 'userb', 'did:example:boost:1', {
             enableRefresh: true,
             skipNotification: true,
         });
 
-        expect(uri).toEqual('managed-credential-uri');
+        // Refresh-enabled callers receive the issuance receipt alongside the
+        // credential URI (LC-2198 decision 4).
+        expect(result).toEqual({
+            credentialUri: 'managed-credential-uri',
+            refresh: {
+                refreshId: REFRESH_ID,
+                refreshService: ALLOCATION.refreshService,
+                credentialId: expect.stringMatching(
+                    /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+                ),
+                issuerDid: PROFILE.did,
+                holderDid: TARGET_DID,
+            },
+        });
 
         // A stable UUID credential ID is generated when the template has none
         expect(client.credentialRefresh.allocateCredentialRefresh.mutate).toHaveBeenCalledTimes(1);
@@ -449,6 +576,9 @@ describe('credential refresh methods', () => {
         expect(allocateInput.credentialId).toMatch(
             /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
         );
+        expect(
+            (result as unknown as { refresh: { credentialId: string } }).refresh.credentialId
+        ).toEqual(allocateInput.credentialId);
 
         // Allocation happens before signing so the service lands in the signed payload
         const allocateOrder =
@@ -483,6 +613,27 @@ describe('credential refresh methods', () => {
         expect(client.utilities.getDid.query).not.toHaveBeenCalled();
     });
 
+    it('sendBoost receipt preserves the exact credentialStatus descriptor from the signed VC', async () => {
+        const client = getMockClient();
+        vi.mocked(getBrainClient).mockResolvedValue(client as never);
+        const { learnCard } = getMockIssuingLearnCard();
+        const credentialStatus = {
+            id: 'https://network.example/status/3#94567',
+            type: 'BitstringStatusListEntry',
+            statusPurpose: 'revocation',
+            statusListIndex: '94567',
+            statusListCredential: 'https://network.example/status/3',
+        };
+        client.boost.allocateCredentialStatus.mutate.mockResolvedValue([credentialStatus]);
+        const plugin = await getLearnCardNetworkPlugin(learnCard, 'https://network.example/trpc');
+
+        const result = (await plugin.methods?.sendBoost(learnCard, 'userb', 'did:example:boost:1', {
+            enableRefresh: true,
+        })) as unknown as { refresh: Record<string, unknown> };
+
+        expect(result.refresh.credentialStatus).toEqual(credentialStatus);
+    });
+
     it('sendBoost with enableRefresh reuses an existing credential ID', async () => {
         const client = getMockClient();
         vi.mocked(getBrainClient).mockResolvedValue(client as never);

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

@@ -0,0 +1,152 @@
+/**
+ * LC-2198 Task 3 — compile-time verification of the `sendBoost` return-shape opt-in
+ * and the unified `send` refresh contract, exercised through the REAL plugin type
+ * system (`LearnCard<...>['invoke']` composition).
+ *
+ * The package Vitest config enables typechecking, so `bun run test` checks
+ * these assertions with the TypeScript compiler alongside the runtime tests.
+ */
+import { describe, expectTypeOf, it } from 'vitest';
+import type { LearnCard, Plugin } from '@learncard/core';
+import type { ManagedCredentialRefreshReceipt } from '@learncard/types';
+
+import type {
+    LearnCardNetworkPlugin,
+    SendBoostNetworkOptions,
+    SendBoostRefreshResult,
+} from '../types';
+
+/** Minimal host plugin so the network plugin is composed through the real machinery. */
+declare const basePlugin: Plugin<'Minimal'>;
+
+/**
+ * The composed wallet type — identical to how `initLearnCard` / `addPlugin` derive
+ * `learnCard.invoke` (`GetPluginMethods` → `UnionToIntersection` over the plugins'
+ * declared methods).
+ */
+type NetworkLearnCard = LearnCard<[typeof basePlugin, LearnCardNetworkPlugin]>;
+type NetworkInvoke = NetworkLearnCard['invoke'];
+
+describe('learnCard.invoke.sendBoost return-shape opt-in', () => {
+    const sendBoost = {} as NetworkInvoke['sendBoost'];
+
+    it('keeps the legacy string result for omitted options', () => {
+        expectTypeOf(sendBoost('userb', 'did:web:example:boost:1')).toEqualTypeOf<
+            Promise<string>
+        >();
+    });
+
+    it('keeps the legacy string result for legacy boolean options', () => {
+        expectTypeOf(sendBoost('userb', 'did:web:example:boost:1', true)).toEqualTypeOf<
+            Promise<string>
+        >();
+        expectTypeOf(sendBoost('userb', 'did:web:example:boost:1', false)).toEqualTypeOf<
+            Promise<string>
+        >();
+    });
+
+    it('keeps the legacy string result when enableRefresh is absent or false', () => {
+        expectTypeOf(
+            sendBoost('userb', 'did:web:example:boost:1', {
+                encrypt: false,
+                skipNotification: true,
+            })
+        ).toEqualTypeOf<Promise<string>>();
+        expectTypeOf(
+            sendBoost('userb', 'did:web:example:boost:1', { enableRefresh: false })
+        ).toEqualTypeOf<Promise<string>>();
+    });
+
+    it('returns the refreshable issuance result for literal enableRefresh: true', () => {
+        expectTypeOf(
+            sendBoost('userb', 'did:web:example:boost:1', { enableRefresh: true })
+        ).toEqualTypeOf<Promise<SendBoostRefreshResult>>();
+        expectTypeOf(
+            sendBoost('userb', 'did:web:example:boost:1', {
+                enableRefresh: true,
+                skipNotification: true,
+            })
+        ).toEqualTypeOf<Promise<SendBoostRefreshResult>>();
+    });
+
+    it('preserves the literal opt-in with status purposes and nested template data', () => {
+        expectTypeOf(
+            sendBoost('userb', 'did:web:example:boost:1', {
+                enableRefresh: true,
+                statusPurposes: ['revocation'],
+                templateData: { grade: 'A' },
+            })
+        ).toEqualTypeOf<Promise<SendBoostRefreshResult>>();
+    });
+
+    it('degrades to the union for a dynamically typed enableRefresh boolean', () => {
+        const dynamic: boolean = Math.random() > 0.5;
+
+        expectTypeOf(
+            sendBoost('userb', 'did:web:example:boost:1', { enableRefresh: dynamic })
+        ).toEqualTypeOf<Promise<string | SendBoostRefreshResult>>();
+    });
+
+    it('degrades to the union when options are typed with an optional enableRefresh', () => {
+        const options: SendBoostNetworkOptions = { enableRefresh: true };
+
+        expectTypeOf(sendBoost('userb', 'did:web:example:boost:1', options)).toEqualTypeOf<
+            Promise<string | SendBoostRefreshResult>
+        >();
+    });
+
+    it('degrades to the union for boolean-or-object option variables', () => {
+        const options = {} as boolean | SendBoostNetworkOptions;
+
+        expectTypeOf(sendBoost('userb', 'did:web:example:boost:1', options)).toEqualTypeOf<
+            Promise<string | SendBoostRefreshResult>
+        >();
+    });
+
+    it('keeps the string result for object options that omit enableRefresh', () => {
+        expectTypeOf(
+            sendBoost('userb', 'did:web:example:boost:1', { encrypt: true, skipNotification: true })
+        ).toEqualTypeOf<Promise<string>>();
+    });
+
+    it('returns a metadata-only receipt carrying the publication inputs', () => {
+        expectTypeOf<
+            SendBoostRefreshResult['refresh']
+        >().toEqualTypeOf<ManagedCredentialRefreshReceipt>();
+
+        // Required publication inputs (identity fields are mandatory; the exact
+        // credentialStatus descriptor is optional because not every VC carries one).
+        expectTypeOf<
+            Pick<
+                SendBoostRefreshResult['refresh'],
+                'refreshId' | 'refreshService' | 'credentialId' | 'issuerDid' | 'holderDid'
+            >
+        >().toBeObject();
+    });
+});
+
+describe('learnCard.invoke.send unified refresh contract', () => {
+    const send = {} as NetworkInvoke['send'];
+
+    it('accepts refresh: true on boost sends and may resolve with the receipt', async () => {
+        const result = await send({
+            type: 'boost',
+            recipient: 'userb',
+            templateUri: 'did:web:example:boost:1',
+            refresh: true,
+        });
+
+        expectTypeOf(result).toMatchTypeOf<{
+            uri: string;
+            credentialUri: string;
+            activityId: string;
+        }>();
+        expectTypeOf(result.refresh).toEqualTypeOf<ManagedCredentialRefreshReceipt | undefined>();
+    });
+
+    it('keeps the refresh flag optional on the unified send input', () => {
+        expectTypeOf<Parameters<NetworkInvoke['send']>[0]['refresh']>().toEqualTypeOf<
+            boolean | undefined
+        >();
+    });
+});