@memberjunction/server 6.2.0-edge.2 → 6.2.0-edge.4

package/src/__tests__/FetchEntityVectorsResolver.test.ts

@@ -0,0 +1,285 @@
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { UserInfo, type DatabaseProviderBase, type EntityInfo, type RunViewParams } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+import type { VectorDBBase } from '@memberjunction/ai-vectordb';
+
+type ViewResult = { Success: boolean; Results: unknown[]; ErrorMessage?: string };
+type RunViewHandler = (params: RunViewParams, contextUser: UserInfo | undefined) => ViewResult;
+
+// Vitest's transform emits no decorator metadata, so type-graphql can't infer field types —
+// stub the decorators; these tests exercise the resolver method, not the schema.
+vi.mock('type-graphql', () => {
+    const decoratorFactory = (..._args: unknown[]) => (..._decorated: unknown[]) => undefined;
+    const exportNames = [
+        'Resolver', 'Query', 'Mutation', 'Subscription', 'Arg', 'Args', 'ArgsType', 'Ctx', 'Root',
+        'Info', 'Field', 'FieldResolver', 'ObjectType', 'InputType', 'InterfaceType', 'Authorized',
+        'UseMiddleware', 'Extensions', 'Directive', 'ID', 'Int', 'Float', 'GraphQLISODateTime',
+        'GraphQLTimestamp', 'registerEnumType', 'createMethodDecorator', 'createParamDecorator',
+        'buildSchema', 'buildSchemaSync', 'PubSub',
+    ];
+    return Object.fromEntries(exportNames.map((name) => [name, decoratorFactory]));
+});
+
+const runViewCalls: Array<{ params: RunViewParams; contextUser: UserInfo | undefined }> = [];
+let runViewHandler: RunViewHandler = () => ({ Success: true, Results: [] });
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    class MockRunView {
+        async RunView(params: RunViewParams, contextUser?: UserInfo): Promise<ViewResult> {
+            runViewCalls.push({ params, contextUser });
+            return runViewHandler(params, contextUser);
+        }
+    }
+    return { ...actual, RunView: MockRunView, LogStatus: () => undefined, LogError: () => undefined };
+});
+
+// GetAIAPIKey resolves through the ClassFactory too; keep it off the CreateInstance spy below.
+vi.mock('@memberjunction/ai', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/ai')>();
+    return { ...actual, GetAIAPIKey: () => 'test-key' };
+});
+
+vi.mock('@memberjunction/aiengine', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/aiengine')>();
+    return { ...actual, AIEngine: { Instance: { GetProviderIndexName: () => 'provider-index-name' } } };
+});
+
+import { FetchEntityVectorsResolver } from '../resolvers/FetchEntityVectorsResolver.js';
+import type { AppContext } from '../types.js';
+
+/* ───── fixtures ───── */
+
+const DOC_ID = 'DOC-1';
+const contextUser = new UserInfo();
+
+const membersEntity = {
+    Name: 'Members',
+    PrimaryKeys: [{ Name: 'ID' }],
+    Fields: [
+        { Name: 'ID', IsNameField: false },
+        { Name: 'FirstName', IsNameField: true },
+        { Name: 'LastName', IsNameField: true },
+        { Name: 'Email', IsNameField: false },
+    ],
+    NameField: undefined,
+} as unknown as EntityInfo;
+
+const orderLinesEntity = {
+    Name: 'Order Lines',
+    PrimaryKeys: [{ Name: 'OrderID' }, { Name: 'LineNo' }],
+    Fields: [
+        { Name: 'OrderID', IsNameField: false },
+        { Name: 'LineNo', IsNameField: false },
+        { Name: 'Description', IsNameField: false },
+    ],
+    NameField: { Name: 'Description' },
+} as unknown as EntityInfo;
+
+function fakeVectorDB(queryKeyIsEntityDocumentID: boolean) {
+    const queryIndex = vi.fn().mockResolvedValue({
+        success: true,
+        data: { matches: [{ id: 'pc-1', values: [0.5, 0.5], metadata: { Entity: 'Members', RecordID: 'a' } }] },
+    });
+    const db = { QueryKeyIsEntityDocumentID: queryKeyIsEntityDocumentID, QueryIndex: queryIndex } as unknown as VectorDBBase;
+    return { db, queryIndex };
+}
+
+function appContext(entityInfo: EntityInfo): AppContext {
+    const provider = { EntityByName: (name: string) => (name === entityInfo.Name ? entityInfo : undefined) } as unknown as DatabaseProviderBase;
+    return {
+        userPayload: { email: 'test@example.com', sessionId: 's', userRecord: contextUser },
+        providers: [{ type: 'Read-Only', provider }],
+    } as unknown as AppContext;
+}
+
+/** Route RunView by entity: the doc → index → database lookups, then the case-specific views. */
+function routeViews(entityName: string, views: Record<string, (params: RunViewParams) => ViewResult>): void {
+    runViewHandler = (params) => {
+        switch (params.EntityName) {
+            case 'MJ: Entity Documents':
+                return { Success: true, Results: [{ ID: DOC_ID, Name: 'Doc', Entity: entityName, VectorIndexID: 'VI-1' }] };
+            case 'MJ: Vector Indexes':
+                return { Success: true, Results: [{ ID: 'VI-1', Name: 'Index', VectorDatabaseID: 'VDB-1', Dimensions: 2 }] };
+            case 'MJ: Vector Databases':
+                return { Success: true, Results: [{ ID: 'VDB-1', ClassKey: 'TestVectorDB' }] };
+            default: {
+                const view = views[params.EntityName ?? ''];
+                return view ? view(params) : { Success: false, Results: [], ErrorMessage: `unexpected view ${params.EntityName}` };
+            }
+        }
+    };
+}
+
+const storedRows = [
+    { ID: 'ERD-1', RecordID: 'AAA', VectorJSON: '[0.1,0.2]' },
+    { ID: 'ERD-2', RecordID: 'bbb', VectorJSON: '[0.3,0.4]' },
+    { ID: 'ERD-3', RecordID: 'ccc', VectorJSON: '[0.5,0.6]' },
+];
+const memberRows = [
+    { ID: 'aaa', FirstName: 'Ada', LastName: 'Lovelace' },
+    { ID: 'bbb', FirstName: 'Grace', LastName: 'Hopper' },
+    { ID: 'ccc', FirstName: 'Alan', LastName: null },
+];
+
+function callsFor(entityName: string) {
+    return runViewCalls.filter((c) => c.params.EntityName === entityName);
+}
+
+/* ───── tests ───── */
+
+describe('FetchEntityVectorsResolver', () => {
+    let createInstanceSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        runViewCalls.length = 0;
+    });
+
+    afterEach(() => {
+        createInstanceSpy?.mockRestore();
+    });
+
+    function useVectorDB(queryKeyIsEntityDocumentID: boolean) {
+        const fake = fakeVectorDB(queryKeyIsEntityDocumentID);
+        createInstanceSpy = vi.spyOn(MJGlobal.Instance.ClassFactory, 'CreateInstance').mockReturnValue(fake.db);
+        return fake;
+    }
+
+    describe('local vector store (QueryKeyIsEntityDocumentID)', () => {
+        it('reads VectorJSON for the document with the context user instead of calling QueryIndex', async () => {
+            const { queryIndex } = useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: true, Results: storedRows }),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(result.ErrorMessage).toBeUndefined();
+            expect(result.Success).toBe(true);
+            expect(queryIndex).not.toHaveBeenCalled();
+            expect(result.TotalCount).toBe(3);
+            expect(result.Results.map((r) => r.ID)).toEqual(['ERD-1', 'ERD-2', 'ERD-3']);
+            expect(result.Results.map((r) => r.Values)).toEqual([[0.1, 0.2], [0.3, 0.4], [0.5, 0.6]]);
+
+            const [erdCall] = callsFor('MJ: Entity Record Documents');
+            expect(erdCall.contextUser).toBe(contextUser);
+            expect(erdCall.params.ExtraFilter).toBe(`EntityDocumentID='${DOC_ID}' AND VectorJSON IS NOT NULL`);
+            expect(erdCall.params.Fields).toEqual(['ID', 'RecordID', 'VectorJSON']);
+            expect(erdCall.params.ResultType).toBe('simple');
+            expect(erdCall.params.IgnoreMaxRows).toBe(true);
+        });
+
+        it('labels each item with Entity, RecordID and the record name fields (RecordID matched case-insensitively)', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: true, Results: storedRows }),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(result.Results.map((r) => JSON.parse(r.Metadata))).toEqual([
+                { Entity: 'Members', RecordID: 'AAA', FirstName: 'Ada', LastName: 'Lovelace' },
+                { Entity: 'Members', RecordID: 'bbb', FirstName: 'Grace', LastName: 'Hopper' },
+                { Entity: 'Members', RecordID: 'ccc', FirstName: 'Alan' },
+            ]);
+            const [membersCall] = callsFor('Members');
+            expect(membersCall.contextUser).toBe(contextUser);
+            expect(membersCall.params.Fields).toEqual(['ID', 'FirstName', 'LastName']);
+            expect(membersCall.params.ResultType).toBe('simple');
+            expect(membersCall.params.ExtraFilter).toBeUndefined();
+        });
+
+        it('honours the filter: passes it to the entity view and drops vectors whose record did not pass', async () => {
+            useVectorDB(true);
+            const filter = "LastName = 'Hopper'";
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: true, Results: storedRows }),
+                Members: (params) => ({
+                    Success: true,
+                    Results: params.ExtraFilter === filter ? memberRows.filter((r) => r.LastName === 'Hopper') : memberRows,
+                }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, filter, appContext(membersEntity));
+
+            expect(result.Success).toBe(true);
+            expect(callsFor('Members')[0].params.ExtraFilter).toBe(filter);
+            expect(result.TotalCount).toBe(1);
+            expect(result.Results[0].ID).toBe('ERD-2');
+            expect(JSON.parse(result.Results[0].Metadata)).toEqual({ Entity: 'Members', RecordID: 'bbb', FirstName: 'Grace', LastName: 'Hopper' });
+        });
+
+        it('stops at maxRecords', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: true, Results: storedRows }),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, 2, undefined, appContext(membersEntity));
+
+            expect(result.Results.map((r) => r.ID)).toEqual(['ERD-1', 'ERD-2']);
+            expect(result.TotalCount).toBe(2);
+        });
+
+        it('matches composite-key records by the compact RecordID segment and falls back to NameField for labels', async () => {
+            useVectorDB(true);
+            routeViews('Order Lines', {
+                'MJ: Entity Record Documents': () => ({
+                    Success: true,
+                    Results: [{ ID: 'ERD-9', RecordID: 'OrderID|o-1||LineNo|2', VectorJSON: '[1,0]' }],
+                }),
+                'Order Lines': () => ({ Success: true, Results: [{ OrderID: 'o-1', LineNo: 2, Description: 'Brie wheel' }] }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(orderLinesEntity));
+
+            expect(result.Success).toBe(true);
+            expect(result.Results).toHaveLength(1);
+            expect(JSON.parse(result.Results[0].Metadata)).toEqual({
+                Entity: 'Order Lines',
+                RecordID: 'OrderID|o-1||LineNo|2',
+                Description: 'Brie wheel',
+            });
+            expect(callsFor('Order Lines')[0].params.Fields).toEqual(['OrderID', 'LineNo', 'Description']);
+        });
+
+        it('returns an error result when the entity records cannot be loaded (e.g. an invalid filter)', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: true, Results: storedRows }),
+                Members: () => ({ Success: false, Results: [], ErrorMessage: 'bad filter' }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, 'nonsense', appContext(membersEntity));
+
+            expect(result.Success).toBe(false);
+            expect(result.Results).toEqual([]);
+            expect(result.ErrorMessage).toBe('Failed to load "Members" records: bad filter');
+        });
+    });
+
+    describe('index-keyed providers (Pinecone path, unchanged)', () => {
+        it('queries the provider index by name and never reads Entity Record Documents', async () => {
+            const { queryIndex } = useVectorDB(false);
+            routeViews('Members', {});
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, 50, undefined, appContext(membersEntity));
+
+            expect(result.Success).toBe(true);
+            expect(queryIndex).toHaveBeenCalledTimes(1);
+            const query = queryIndex.mock.calls[0][0];
+            expect(query.id).toBe('provider-index-name');
+            expect(query.topK).toBe(50);
+            expect(query.includeValues).toBe(true);
+            expect(query.filter).toEqual({ Entity: { $eq: 'Members' } });
+            expect(query.vector).toHaveLength(2);
+            expect(result.Results).toEqual([{ ID: 'pc-1', Values: [0.5, 0.5], Metadata: JSON.stringify({ Entity: 'Members', RecordID: 'a' }) }]);
+            expect(callsFor('MJ: Entity Record Documents')).toHaveLength(0);
+            expect(callsFor('Members')).toHaveLength(0);
+        });
+    });
+});

package/src/__tests__/HostInstance.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { hostname } from 'os';
+
+const { logErrorMock } = vi.hoisted(() => ({ logErrorMock: vi.fn() }));
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    return { ...actual, LogError: logErrorMock };
+});
+
+import { HostInstanceIdentity } from '../agentSessions/HostInstance.js';
+
+/** A fresh copy of the module: no port set, no identity read yet. */
+async function freshHostInstanceModule(): Promise<typeof import('../agentSessions/HostInstance.js')> {
+    vi.resetModules();
+    return import('../agentSessions/HostInstance.js');
+}
+
+beforeEach(() => {
+    logErrorMock.mockReset();
+});
+
+describe('HostInstanceIdentity', () => {
+    const ours = new HostInstanceIdentity('build-01', '4000', 101, 'boot-ours');
+
+    it('stamps hostname:port:pid:bootId, and every boot of the instance shares hostname:port:', () => {
+        expect(ours.GetHostInstanceID()).toBe('build-01:4000:101:boot-ours');
+        expect(ours.GetInstancePrefix()).toBe('build-01:4000:');
+    });
+
+    describe('IsPriorBoot', () => {
+        it('is true for an earlier boot of the same instance, including one whose pid the OS reused', () => {
+            expect(ours.IsPriorBoot('build-01:4000:99:boot-before')).toBe(true);
+            expect(ours.IsPriorBoot('build-01:4000:101:boot-before')).toBe(true);
+        });
+
+        it.each([
+            ['this boot', 'build-01:4000:101:boot-ours'],
+            ['another MJAPI on the same host (another port)', 'build-01:4100:202:boot-other'],
+            ['an MJAPI on another host', 'build-02:4000:101:boot-other'],
+            ['the format before the port was added, with a pid equal to the port', 'build-01:4000:boot-before'],
+            ['no id', null],
+            ['an empty id', ''],
+        ])('is false for %s', (_case, hostInstanceID) => {
+            expect(ours.IsPriorBoot(hostInstanceID)).toBe(false);
+        });
+
+        it("matches a host name exactly, though a SQL LIKE reads its '_' as any character", () => {
+            const underscored = new HostInstanceIdentity('web_1', '4000', 7, 'boot-ours');
+            expect(underscored.IsPriorBoot('web_1:4000:8:boot-before')).toBe(true);
+            expect(underscored.IsPriorBoot('web-1:4000:8:boot-before')).toBe(false);
+        });
+    });
+});
+
+describe('the current host instance', () => {
+    it('carries the port SetHostInstancePort set before it was first read', async () => {
+        const hostInstance = await freshHostInstanceModule();
+        hostInstance.SetHostInstancePort(4100);
+
+        const current = hostInstance.GetCurrentHostInstance();
+        expect(current.GetHostInstanceID()).toBe(`${hostname()}:4100:${process.pid}:${hostInstance.GetBootID()}`);
+        expect(current.GetInstancePrefix()).toBe(`${hostname()}:4100:`);
+        expect(hostInstance.GetHostInstanceID()).toBe(current.GetHostInstanceID());
+    });
+
+    it('is this process alone (pid-<pid>) when no port was set', async () => {
+        const hostInstance = await freshHostInstanceModule();
+
+        expect(hostInstance.GetCurrentHostInstance().InstanceKey).toBe(`pid-${process.pid}`);
+        expect(hostInstance.GetHostInstanceID()).toBe(`${hostname()}:pid-${process.pid}:${process.pid}:${hostInstance.GetBootID()}`);
+    });
+
+    it('keeps its identity, and logs, when another port is set after it was read', async () => {
+        const hostInstance = await freshHostInstanceModule();
+        hostInstance.SetHostInstancePort(4100);
+        const before = hostInstance.GetHostInstanceID();
+
+        hostInstance.SetHostInstancePort(4200);
+
+        expect(hostInstance.GetHostInstanceID()).toBe(before);
+        expect(logErrorMock).toHaveBeenCalledTimes(1);
+        expect(String(logErrorMock.mock.calls[0][0])).toContain('Port 4200 was set after');
+    });
+});

package/src/__tests__/HumanHandoffResolver.test.ts

@@ -0,0 +1,250 @@
+// type-graphql decorators on the resolver call Reflect.getMetadata, which only exists when this polyfill
+// is loaded first. Vitest does not bring it in automatically — this MUST precede the resolver import.
+import 'reflect-metadata';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+
+const h = vi.hoisted(() => ({
+  configure: vi.fn(),
+  registryConfigure: vi.fn(),
+  getSystemUser: vi.fn(),
+  listOffersForUser: vi.fn(),
+  acceptOffer: vi.fn(),
+  declineOffer: vi.fn(),
+  notificationConfig: vi.fn(async () => undefined),
+  sendNotification: vi.fn(async () => ({ success: true, deliveryChannels: { inApp: true, email: false, sms: false } })),
+}));
+
+vi.mock('@memberjunction/livekit-room-server', () => ({
+  RoomHandoffEngine: {
+    Instance: {
+      Configure: h.configure,
+      ListOffersForUser: h.listOffersForUser,
+      AcceptOffer: h.acceptOffer,
+      DeclineOffer: h.declineOffer,
+    },
+  },
+  HandoffOfferRegistry: { Instance: { Configure: h.registryConfigure } },
+  LiveKitSipService: class {},
+}));
+vi.mock('@memberjunction/generic-database-provider', () => ({
+  UserCache: { Instance: { GetSystemUser: h.getSystemUser } },
+}));
+vi.mock('@memberjunction/notifications', () => ({
+  NotificationEngine: { Instance: { Config: h.notificationConfig, SendNotification: h.sendNotification } },
+}));
+
+import {
+  HumanHandoffResolver,
+  HandoffOfferChangeFilter,
+  NotificationHandoffNotifier,
+  PubSubHandoffPublisher,
+  SetHandoffOfferPublishHook,
+  ParseReplicatedHandoffOfferUpdate,
+  HANDOFF_OFFER_TOPIC,
+} from '../resolvers/HumanHandoffResolver';
+import { PubSubManager } from '../generic/PubSubManager.js';
+import type { AppContext } from '../types.js';
+
+/** Captured at module load: the resolver binds the engine's server-only collaborators then. */
+const wiredAtLoad = h.configure.mock.calls[0]?.[0] as { Presence: unknown; Publisher: unknown; Notifier: unknown };
+
+const registryWiredAtLoad = h.registryConfigure.mock.calls[0]?.[0] as { ResolveContextUser: () => UserInfo | undefined };
+
+describe('offer registry server identity wiring', () => {
+  it('configures the registry with a lazy system-user resolver that reads the user cache on every call', () => {
+    const systemUser = { ID: 'sys' } as unknown as UserInfo;
+    h.getSystemUser.mockReturnValueOnce(undefined).mockReturnValueOnce(systemUser);
+    expect(registryWiredAtLoad.ResolveContextUser()).toBeUndefined();
+    expect(registryWiredAtLoad.ResolveContextUser()).toBe(systemUser);
+  });
+});
+
+class TestableResolver extends HumanHandoffResolver {
+  public user: UserInfo | undefined = { ID: 'U1', Name: 'Dana', Email: 'dana@x.com' } as unknown as UserInfo;
+  protected override GetUserFromPayload(): UserInfo | undefined {
+    return this.user;
+  }
+}
+
+const ctx = {} as AppContext;
+
+const VIEW = {
+  OfferID: 'offer-1',
+  RoomName: 'call-1',
+  Mode: 'warm',
+  Summary: 'Wants a refund',
+  CallerLabel: 'Phone caller ****0123',
+  AgentName: 'Sage',
+  Status: 'Pending',
+  CreatedAt: '2026-10-03T10:00:00.000Z',
+  ExpiresAt: '2026-10-03T10:00:45.000Z',
+  InteractionID: 'int-123',
+};
+
+describe('HumanHandoffResolver', () => {
+  let resolver: TestableResolver;
+
+  beforeEach(() => {
+    resolver = new TestableResolver();
+    h.listOffersForUser.mockReset();
+    h.acceptOffer.mockReset();
+    h.declineOffer.mockReset();
+    h.sendNotification.mockClear();
+    h.notificationConfig.mockClear();
+  });
+
+  it('gives the handoff engine its server-only collaborators when the module loads', () => {
+    expect(wiredAtLoad.Presence).toBeDefined();
+    expect(wiredAtLoad.Publisher).toBeInstanceOf(PubSubHandoffPublisher);
+    expect(wiredAtLoad.Notifier).toBeInstanceOf(NotificationHandoffNotifier);
+  });
+
+  describe('MyHandoffOffers', () => {
+    it('lists the signed-in user\'s offers, and only asks the engine about that user', async () => {
+      h.listOffersForUser.mockReturnValue([VIEW]);
+      const offers = await resolver.MyHandoffOffers(ctx);
+      expect(h.listOffersForUser).toHaveBeenCalledWith('U1', resolver.user);
+      expect(offers).toEqual([VIEW]);
+    });
+
+    it('returns nothing when there is no signed-in user', async () => {
+      resolver.user = undefined;
+      expect(await resolver.MyHandoffOffers(ctx)).toEqual([]);
+      expect(h.listOffersForUser).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('AcceptHandoffOffer', () => {
+    it('accepts as the signed-in user (never a user id from the client) and returns the room to join', async () => {
+      h.acceptOffer.mockReturnValue({ Ok: true, Offer: { ...VIEW, Status: 'Accepted' } });
+      const result = await resolver.AcceptHandoffOffer('offer-1', ctx);
+      expect(h.acceptOffer).toHaveBeenCalledWith('offer-1', 'U1', resolver.user);
+      expect(result).toMatchObject({ Success: true, RoomName: 'call-1', Offer: { Status: 'Accepted' } });
+    });
+
+    it('passes the engine\'s refusal back without a room', async () => {
+      h.acceptOffer.mockReturnValue({ Ok: false, Reason: 'This conversation offer is no longer available.' });
+      expect(await resolver.AcceptHandoffOffer('offer-1', ctx)).toEqual({ Success: false, ErrorMessage: 'This conversation offer is no longer available.', RoomName: '' });
+    });
+
+    it('requires a signed-in user', async () => {
+      resolver.user = undefined;
+      const result = await resolver.AcceptHandoffOffer('offer-1', ctx);
+      expect(result.Success).toBe(false);
+      expect(h.acceptOffer).not.toHaveBeenCalled();
+    });
+
+    it('turns an engine failure into a plain failure', async () => {
+      h.acceptOffer.mockImplementation(() => {
+        throw new Error('boom');
+      });
+      expect(await resolver.AcceptHandoffOffer('offer-1', ctx)).toMatchObject({ Success: false, RoomName: '' });
+    });
+  });
+
+  describe('DeclineHandoffOffer', () => {
+    it('declines as the signed-in user', async () => {
+      h.declineOffer.mockReturnValue({ Ok: true });
+      expect(await resolver.DeclineHandoffOffer('offer-1', ctx)).toEqual({ Success: true });
+      expect(h.declineOffer).toHaveBeenCalledWith('offer-1', 'U1', resolver.user);
+    });
+
+    it('passes a refusal back, and requires a user', async () => {
+      h.declineOffer.mockReturnValue({ Ok: false, Reason: 'gone' });
+      expect(await resolver.DeclineHandoffOffer('offer-1', ctx)).toEqual({ Success: false, ErrorMessage: 'gone' });
+      resolver.user = undefined;
+      expect((await resolver.DeclineHandoffOffer('offer-1', ctx)).Success).toBe(false);
+    });
+  });
+
+  describe('HandoffOfferChanges (subscription)', () => {
+    it('shapes the payload for the client and drops the server-side delivery key', () => {
+      const change = resolver.HandoffOfferChanges({ UserID: 'U1', Kind: 'offered', Offer: VIEW as never });
+      expect(change).toEqual({ Kind: 'offered', Offer: VIEW });
+      expect(JSON.stringify(change)).not.toContain('U1');
+    });
+  });
+});
+
+describe('HandoffOfferChangeFilter', () => {
+  const payload = { UserID: 'AAAAAAAA-0000-0000-0000-000000000001', Kind: 'offered' as const, Offer: VIEW as never };
+  const context = (id?: string) => ({ userPayload: { userRecord: { ID: id } } });
+
+  it('delivers a change only to the person it belongs to, comparing ids case-insensitively', () => {
+    expect(HandoffOfferChangeFilter({ payload, context: context('aaaaaaaa-0000-0000-0000-000000000001') })).toBe(true);
+    expect(HandoffOfferChangeFilter({ payload, context: context('BBBBBBBB-0000-0000-0000-000000000002') })).toBe(false);
+  });
+
+  it('fails closed when either identity is missing', () => {
+    expect(HandoffOfferChangeFilter({ payload, context: undefined })).toBe(false);
+    expect(HandoffOfferChangeFilter({ payload, context: context(undefined) })).toBe(false);
+    expect(HandoffOfferChangeFilter({ payload: { ...payload, UserID: '' }, context: context('x') })).toBe(false);
+  });
+});
+
+describe('PubSubHandoffPublisher', () => {
+  it('publishes the change on the offer topic, keyed by the person it belongs to', () => {
+    const publish = vi.spyOn(PubSubManager.Instance, 'Publish').mockImplementation(() => undefined);
+    new PubSubHandoffPublisher().Publish({ UserID: 'U1', Kind: 'updated', Offer: VIEW as never });
+    expect(publish).toHaveBeenCalledWith(HANDOFF_OFFER_TOPIC, { UserID: 'U1', Kind: 'updated', Offer: VIEW });
+    publish.mockRestore();
+  });
+
+  it('forwards the change to the cluster hook if set', () => {
+    const hook = vi.fn();
+    SetHandoffOfferPublishHook(hook);
+    new PubSubHandoffPublisher().Publish({ UserID: 'U1', Kind: 'updated', Offer: VIEW as never });
+    expect(hook).toHaveBeenCalledWith(expect.objectContaining({ UserID: 'U1', Kind: 'updated', Offer: VIEW }));
+    SetHandoffOfferPublishHook(null);
+  });
+});
+
+describe('ParseReplicatedHandoffOfferUpdate', () => {
+  it('parses valid replicated offer payload', () => {
+    const raw = JSON.stringify({
+      UserID: 'U1',
+      Kind: 'updated',
+      Offer: VIEW,
+    });
+    const parsed = ParseReplicatedHandoffOfferUpdate(raw);
+    expect(parsed).toMatchObject({
+      UserID: 'U1',
+      Kind: 'updated',
+      Offer: { OfferID: 'offer-1' },
+    });
+  });
+
+  it('rejects invalid payloads cleanly', () => {
+    expect(ParseReplicatedHandoffOfferUpdate('invalid json')).toBeNull();
+    expect(ParseReplicatedHandoffOfferUpdate(JSON.stringify({ Kind: 'unknown' }))).toBeNull();
+    expect(ParseReplicatedHandoffOfferUpdate(JSON.stringify({ Kind: 'updated' }))).toBeNull();
+  });
+});
+
+describe('NotificationHandoffNotifier', () => {
+  const user = { ID: 'run-as' } as unknown as UserInfo;
+  const provider = {} as unknown as IMetadataProvider;
+
+  it('sends a notification to the person, routed to the handoff console, through the dedicated handoff offer type', async () => {
+    await new NotificationHandoffNotifier().NotifyOffer(VIEW as never, 'U1', user, provider);
+    expect(h.notificationConfig).toHaveBeenCalledWith(false, user, provider);
+    expect(h.sendNotification).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userId: 'U1',
+        typeNameOrId: 'Conversation Handoff Offer',
+        title: expect.stringContaining('Phone caller ****0123'),
+        message: expect.stringContaining('Wants a refund'),
+        resourceConfiguration: { type: 'handoff-offer', offerId: 'offer-1', room: 'call-1' },
+      }),
+      user,
+    );
+  });
+
+  it('throws (so the engine logs it) when the notification engine reports a failure', async () => {
+    h.sendNotification.mockResolvedValueOnce({ success: false, errors: ['type not found'], deliveryChannels: { inApp: false, email: false, sms: false } } as never);
+    await expect(new NotificationHandoffNotifier().NotifyOffer(VIEW as never, 'U1', user, provider)).rejects.toThrow('type not found');
+  });
+});
+