@memberjunction/server 5.30.1 → 5.31.0

package/src/__tests__/TagGovernanceResolver.test.ts

@@ -0,0 +1,255 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+/**
+ * Tests for TagGovernanceResolver.
+ *
+ * type-graphql decorators on the resolver class need a registered TypeGraphQL
+ * runtime to instantiate, so we don't construct the resolver directly. Instead
+ * we verify the resolver wraps the engines correctly by stubbing the engines
+ * and asserting the dispatch contract — what gets called, with what args, and
+ * how errors are surfaced.
+ */
+
+const { promoteCalls, rejectCalls, rebuildCalls, healthCalls, behaviorFlags } = vi.hoisted(() => ({
+    promoteCalls: [] as Array<{ id: string; strategy: unknown; user: unknown }>,
+    rejectCalls: [] as Array<{ id: string; notes: string | null; user: unknown }>,
+    rebuildCalls: [] as Array<{ user: unknown }>,
+    healthCalls: [] as Array<{ thresholds: unknown; user: unknown }>,
+    behaviorFlags: { promoteThrows: false, rejectThrows: false, rebuildThrows: false, healthThrows: false },
+}));
+
+vi.mock('@memberjunction/tag-engine', () => ({
+    TagGovernanceEngine: {
+        Instance: {
+            PromoteSuggestion: async (id: string, strategy: unknown, user: unknown) => {
+                promoteCalls.push({ id, strategy, user });
+                if (behaviorFlags.promoteThrows) throw new Error('promote-fail');
+                return { ID: 'new-tag-id', Name: 'Resolved Tag' };
+            },
+            RejectSuggestion: async (id: string, notes: string | null, user: unknown) => {
+                rejectCalls.push({ id, notes, user });
+                if (behaviorFlags.rejectThrows) throw new Error('reject-fail');
+            },
+        },
+    },
+    TagEngine: {
+        Instance: {
+            RebuildTagEmbeddings: async (user: unknown) => {
+                rebuildCalls.push({ user });
+                if (behaviorFlags.rebuildThrows) throw new Error('rebuild-fail');
+                return { refreshed: 7, total: 100 };
+            },
+        },
+    },
+    TagHealthJob: {
+        Instance: {
+            Run: async (thresholds: unknown, user: unknown) => {
+                healthCalls.push({ thresholds, user });
+                if (behaviorFlags.healthThrows) throw new Error('health-fail');
+                return { mergeCount: 3, lowUsageCount: 2, wideNodeCount: 1, durationMs: 42 };
+            },
+        },
+    },
+    DEFAULT_TAG_HEALTH_THRESHOLDS: {
+        minCoOccurrence: 5,
+        minNameSimilarity: 0.5,
+        minEmbeddingSimilarity: 0.85,
+        maxUsage: 2,
+        maxImplicitChildren: 25,
+    },
+}));
+
+// Minimal type-graphql shim — we only need the decorators to be no-ops so the
+// resolver class can load. Method behavior is what we test.
+vi.mock('type-graphql', () => ({
+    Resolver:    () => () => undefined,
+    Mutation:    () => () => undefined,
+    Query:       () => () => undefined,
+    Ctx:         () => () => undefined,
+    Arg:         () => () => undefined,
+    ObjectType:  () => () => undefined,
+    Field:       () => () => undefined,
+    Int:         () => undefined,
+    Float:       () => undefined,
+}));
+
+vi.mock('@memberjunction/core', () => ({
+    LogError: vi.fn(),
+    LogStatus: vi.fn(),
+}));
+
+// Stub ResolverBase — we only need GetUserFromPayload to return a synthetic user.
+vi.mock('../generic/ResolverBase.js', () => ({
+    ResolverBase: class {
+        GetUserFromPayload(payload: unknown) {
+            if (!payload) return null;
+            return { ID: 'user-1', Email: 'test@example.com' };
+        }
+    },
+}));
+
+import { TagGovernanceResolver } from '../resolvers/TagGovernanceResolver.js';
+
+describe('TagGovernanceResolver', () => {
+    let resolver: TagGovernanceResolver;
+
+    beforeEach(() => {
+        promoteCalls.length = 0;
+        rejectCalls.length = 0;
+        rebuildCalls.length = 0;
+        healthCalls.length = 0;
+        behaviorFlags.promoteThrows = false;
+        behaviorFlags.rejectThrows = false;
+        behaviorFlags.rebuildThrows = false;
+        behaviorFlags.healthThrows = false;
+        resolver = new TagGovernanceResolver();
+    });
+
+    const ctx = (withUser = true) => withUser ? { userPayload: { sub: 'u-1' } } : { userPayload: undefined };
+
+    // ---- PromoteTagSuggestion ----------------------------------------------
+
+    describe('PromoteTagSuggestion', () => {
+        it('rejects when no current user is resolved from the payload', async () => {
+            const r = await resolver.PromoteTagSuggestion('s-1', 'create-new', undefined, ctx(false) as never);
+            expect(r.Success).toBe(false);
+            expect(r.ErrorMessage).toContain('current user');
+            expect(promoteCalls).toHaveLength(0);
+        });
+
+        it('rejects unknown strategies', async () => {
+            const r = await resolver.PromoteTagSuggestion('s-1', 'wat' as never, undefined, ctx() as never);
+            expect(r.Success).toBe(false);
+            expect(r.ErrorMessage).toContain('Unknown strategy');
+            expect(promoteCalls).toHaveLength(0);
+        });
+
+        it('requires targetTagID for merge-into-existing', async () => {
+            const r = await resolver.PromoteTagSuggestion('s-1', 'merge-into-existing', undefined, ctx() as never);
+            expect(r.Success).toBe(false);
+            expect(r.ErrorMessage).toContain('targetTagID is required');
+            expect(promoteCalls).toHaveLength(0);
+        });
+
+        it('dispatches create-new and returns the resolved tag', async () => {
+            const r = await resolver.PromoteTagSuggestion('s-1', 'create-new', undefined, ctx() as never);
+            expect(r.Success).toBe(true);
+            expect(r.ResolvedTagID).toBe('new-tag-id');
+            expect(r.ResolvedTagName).toBe('Resolved Tag');
+            expect(promoteCalls[0].id).toBe('s-1');
+            expect((promoteCalls[0].strategy as { kind: string }).kind).toBe('create-new');
+        });
+
+        it('dispatches merge-into-existing with the target tag ID', async () => {
+            const r = await resolver.PromoteTagSuggestion('s-1', 'merge-into-existing', 'target-tag', ctx() as never);
+            expect(r.Success).toBe(true);
+            expect((promoteCalls[0].strategy as { kind: string; targetTagID: string }).targetTagID).toBe('target-tag');
+        });
+
+        it('returns Success=false with the error message when the engine throws', async () => {
+            behaviorFlags.promoteThrows = true;
+            const r = await resolver.PromoteTagSuggestion('s-1', 'create-new', undefined, ctx() as never);
+            expect(r.Success).toBe(false);
+            expect(r.ErrorMessage).toBe('promote-fail');
+        });
+    });
+
+    // ---- RejectTagSuggestion -----------------------------------------------
+
+    describe('RejectTagSuggestion', () => {
+        it('rejects without a user', async () => {
+            const r = await resolver.RejectTagSuggestion('s-1', undefined, ctx(false) as never);
+            expect(r.Success).toBe(false);
+            expect(rejectCalls).toHaveLength(0);
+        });
+
+        it('passes optional reviewer notes to the engine', async () => {
+            const r = await resolver.RejectTagSuggestion('s-1', 'looked spammy', ctx() as never);
+            expect(r.Success).toBe(true);
+            expect(rejectCalls[0]).toMatchObject({ id: 's-1', notes: 'looked spammy' });
+        });
+
+        it('coerces undefined notes to null', async () => {
+            await resolver.RejectTagSuggestion('s-1', undefined, ctx() as never);
+            expect(rejectCalls[0].notes).toBeNull();
+        });
+
+        it('returns the engine error on failure', async () => {
+            behaviorFlags.rejectThrows = true;
+            const r = await resolver.RejectTagSuggestion('s-1', undefined, ctx() as never);
+            expect(r.Success).toBe(false);
+            expect(r.ErrorMessage).toBe('reject-fail');
+        });
+    });
+
+    // ---- RebuildTagEmbeddings ----------------------------------------------
+
+    describe('RebuildTagEmbeddings', () => {
+        it('rejects without a user', async () => {
+            const r = await resolver.RebuildTagEmbeddings(ctx(false) as never);
+            expect(r.Success).toBe(false);
+            expect(r.Refreshed).toBe(0);
+            expect(r.Total).toBe(0);
+        });
+
+        it('returns the refresh counts from the engine', async () => {
+            const r = await resolver.RebuildTagEmbeddings(ctx() as never);
+            expect(r.Success).toBe(true);
+            expect(r.Refreshed).toBe(7);
+            expect(r.Total).toBe(100);
+            expect(rebuildCalls).toHaveLength(1);
+        });
+
+        it('returns 0/0 with an error message when the engine throws', async () => {
+            behaviorFlags.rebuildThrows = true;
+            const r = await resolver.RebuildTagEmbeddings(ctx() as never);
+            expect(r.Success).toBe(false);
+            expect(r.ErrorMessage).toBe('rebuild-fail');
+            expect(r.Refreshed).toBe(0);
+        });
+    });
+
+    // ---- RunTagHealth ------------------------------------------------------
+
+    describe('RunTagHealth', () => {
+        it('rejects without a user', async () => {
+            const r = await resolver.RunTagHealth(undefined, undefined, undefined, undefined, undefined, ctx(false) as never);
+            expect(r.Success).toBe(false);
+            expect(healthCalls).toHaveLength(0);
+        });
+
+        it('falls back to defaults when no thresholds are supplied', async () => {
+            const r = await resolver.RunTagHealth(undefined, undefined, undefined, undefined, undefined, ctx() as never);
+            expect(r.Success).toBe(true);
+            expect(r.MergeCount).toBe(3);
+            expect(r.LowUsageCount).toBe(2);
+            expect(r.WideNodeCount).toBe(1);
+            const t = healthCalls[0].thresholds as Record<string, number>;
+            expect(t.minCoOccurrence).toBe(5);     // from DEFAULT
+            expect(t.maxImplicitChildren).toBe(25);// from DEFAULT
+        });
+
+        it('overrides only the supplied threshold fields', async () => {
+            await resolver.RunTagHealth(20, 0.7, undefined, 1, undefined, ctx() as never);
+            const t = healthCalls[0].thresholds as Record<string, number>;
+            expect(t.minCoOccurrence).toBe(20);
+            expect(t.minNameSimilarity).toBe(0.7);
+            expect(t.minEmbeddingSimilarity).toBe(0.85); // from DEFAULT
+            expect(t.maxUsage).toBe(1);
+            expect(t.maxImplicitChildren).toBe(25);      // from DEFAULT
+        });
+
+        it('returns the duration alongside the counts', async () => {
+            const r = await resolver.RunTagHealth(undefined, undefined, undefined, undefined, undefined, ctx() as never);
+            expect(r.DurationMs).toBe(42);
+        });
+
+        it('surfaces engine errors with zeroed counts', async () => {
+            behaviorFlags.healthThrows = true;
+            const r = await resolver.RunTagHealth(undefined, undefined, undefined, undefined, undefined, ctx() as never);
+            expect(r.Success).toBe(false);
+            expect(r.MergeCount).toBe(0);
+            expect(r.ErrorMessage).toBe('health-fail');
+        });
+    });
+});

package/src/agents/skip-sdk.ts

@@ -24,7 +24,7 @@ import {
     SkipAPIArtifactType
 } from '@memberjunction/skip-types';
 import { DataContext } from '@memberjunction/data-context';
-import { UserInfo, LogStatus, LogError, Metadata, RunQuery, EntityInfo, EntityFieldInfo, EntityFieldValueInfo, DatabaseProviderBase } from '@memberjunction/core';
+import { IMetadataProvider, UserInfo, LogStatus, LogError, Metadata, RunQuery, EntityInfo, EntityFieldInfo, EntityFieldValueInfo, DatabaseProviderBase } from '@memberjunction/core';
 import { request as httpRequest } from 'http';
 import { request as httpsRequest } from 'https';
 import { gzip as gzipCompress, createGunzip } from 'zlib';
@@ -61,6 +61,15 @@ export interface SkipSDKConfig {
      * Optional organization context information
      */
     organizationInfo?: string;
+
+    /**
+     * Optional metadata provider this SDK instance binds to. When set, every metadata
+     * lookup (entities, queries, schema) and direct SQL call is routed through this
+     * provider — multi-tenant servers should pass the per-request provider here.
+     * When omitted, the SDK falls back to the global `Metadata.Provider` (single-server
+     * mode, legacy callers).
+     */
+    provider?: IMetadataProvider;
 }
 
 /**
@@ -199,6 +208,19 @@ interface SkipStreamMessage {
 export class SkipSDK {
     private config: SkipSDKConfig;
 
+    /**
+     * The metadata provider this SDK instance is bound to. Set via the constructor
+     * config or the `Provider` setter. Falls back to the global `Metadata.Provider`
+     * when not set — multi-tenant servers should always supply an explicit provider
+     * so each request reaches its own database connection.
+     */
+    public get Provider(): IMetadataProvider {
+        return this.config.provider ?? (new Metadata() as unknown as IMetadataProvider);
+    }
+    public set Provider(value: IMetadataProvider | null) {
+        this.config.provider = value ?? undefined;
+    }
+
     // Static cache for Skip entities (shared across all instances)
     private static __skipEntitiesCache$: BehaviorSubject<Promise<EntityInfo[]> | null> = new BehaviorSubject<Promise<EntityInfo[]> | null>(null);
     private static __lastRefreshTime: number = 0;
@@ -460,7 +482,7 @@ export class SkipSDK {
      * Build saved queries for Skip
      */
     private buildQueries(status: "Pending" | "In-Review" | "Approved" | "Rejected" | "Obsolete" = 'Approved'): SkipQueryInfo[] {
-        const md = new Metadata();
+        const md = this.Provider;
         const approvedQueries = md.Queries.filter((q) => q.Status === status);
 
         return approvedQueries.map((q) => ({
@@ -521,7 +543,7 @@ export class SkipSDK {
     /**
      * Recursively build category path for a query
      */
-    private buildQueryCategoryPath(md: Metadata, categoryID: string): string {
+    private buildQueryCategoryPath(md: IMetadataProvider, categoryID: string): string {
         const cat = md.QueryCategories.find((c) => UUIDsEqual(c.ID, categoryID));
         if (!cat) return '';
         if (!cat.ParentID) return cat.Name;
@@ -537,7 +559,7 @@ export class SkipSDK {
      * across all queries, not just approved ones.
      */
     private buildQueryCatalog(): SkipQueryCatalogEntry[] {
-        const md = new Metadata();
+        const md = this.Provider;
 
         return md.Queries.map((q) => ({
             Name: q.Name,
@@ -856,7 +878,7 @@ export class SkipSDK {
      */
     private async refreshSkipEntities(): Promise<EntityInfo[]> {
         try {
-            const md = new Metadata();
+            const md = this.Provider;
 
             // Diagnostic logging
             LogStatus(`[SkipSDK.refreshSkipEntities] Total entities in metadata: ${md.Entities.length}`);
@@ -983,8 +1005,9 @@ export class SkipSDK {
      */
     private async getFieldDistinctValues(f: EntityFieldInfo): Promise<EntityFieldValueInfo[]> {
         try {
-            // Uses the provider's ExecuteSQL so this works on both SQL Server and PostgreSQL.
-            const provider = Metadata.Provider as DatabaseProviderBase;
+            // Use this SDK instance's bound provider so multi-tenant servers route the SQL
+            // through the right connection. ExecuteSQL works on both SQL Server and PostgreSQL.
+            const provider = this.Provider as unknown as DatabaseProviderBase;
             const sql = `SELECT DISTINCT ${f.Name} FROM ${f.SchemaName}.${f.BaseView}`;
             const rows = await provider.ExecuteSQL<Record<string, unknown>>(sql);
             if (!rows || rows.length === 0) {

package/src/auth/exampleNewUserSubClass.ts

@@ -16,7 +16,7 @@ import { MJUserEntity } from '@memberjunction/core-entities';
 export class ExampleNewUserSubClass extends NewUserBase {
   public override async createNewUser(firstName: string, lastName: string, email: string, linkedRecordType: string = 'None', linkedEntityId?: string, linkedEntityRecordId?: string): Promise<MJUserEntity | null> {
     try {
-      const md = new Metadata();
+      const md = new Metadata(); // global-provider-ok: new-user creation runs in the JWT auth flow, before AppContext.providers is built
 
       const contextUser = UserCache.Instance.Users.find(
         (u) => u.Email.trim().toLowerCase() === configInfo?.userHandling?.contextUserForNewUserCreation?.trim().toLowerCase()

package/src/auth/index.ts

@@ -233,7 +233,7 @@ export const verifyUserRecord = async (
         if (newUser) {
           // new user worked! we already have the stuff we need for the cache, so no need to go to the DB now, just create a new UserInfo object and use the return value from the createNewUser method
           // to init it, including passing in the role list for the user.
-          const md: Metadata = new Metadata();
+          const md: Metadata = new Metadata(); // global-provider-ok: JWT validation + role lookup runs BEFORE AppContext.providers is built — no per-request provider yet
 
           const initData: MJUserEntityType & { UserRoles: { UserID: string; RoleName: string; RoleID: string }[] } = newUser.GetAll();
 
@@ -244,7 +244,7 @@ export const verifyUserRecord = async (
             return { UserID: initData.ID, RoleName: role, RoleID: roleID };
           });
 
-          user = new UserInfo(Metadata.Provider, initData);
+          user = new UserInfo(Metadata.Provider, initData); // global-provider-ok: same JWT-validation context — no per-request provider yet
           UserCache.Instance.Users.push(user);
           console.warn(`   >>> New user ${email} created successfully!`);
         }

package/src/auth/newUsers.ts

@@ -24,7 +24,7 @@ export class NewUserBase {
                 }
             }
 
-            const md: Metadata = new Metadata();
+            const md: Metadata = new Metadata(); // global-provider-ok: new-user creation runs in the JWT auth flow, before AppContext.providers is built
             const user = await md.GetEntityObject<MJUserEntity>('MJ: Users', contextUser) // To-Do - change this to be a different defined user for the user creation process
             user.NewRecord();
             user.Name = email;
@@ -46,7 +46,7 @@ export class NewUserBase {
             // Create the user and all of its role/application/app-entity records atomically.
             // If any Save fails partway through, the whole provisioning rolls back so we never
             // leave a half-created user with partial roles/applications behind.
-            const provider = Metadata.Provider as DatabaseProviderBase;
+            const provider = Metadata.Provider as DatabaseProviderBase; // global-provider-ok: new-user creation runs in the JWT auth flow, before AppContext.providers is built
             await provider.BeginTransaction();
             try {
                 if (!await user.Save()) {

package/src/context.ts

@@ -333,8 +333,8 @@ export const contextFunction =
       throw new AuthenticationError('No user payload — auth middleware may not have run');
     }
 
-    if (Metadata.Provider.Entities.length === 0 ) {
-      console.warn('WARNING: No entities found in global/shared metadata, this can often be due to the use of **global** Metadata/RunView/DB Providers in a multi-user environment. Check your code to make sure you are using the providers passed to you in AppContext by MJServer and not calling new Metadata() new RunView() new RunQuery() and similar patterns as those are unstable at times in multi-user server environments!!!');
+    if (Metadata.Provider.Entities.length === 0 ) { // global-provider-ok: diagnostic warning about global provider state
+      console.warn('WARNING: No entities found in global/shared metadata, this can often be due to the use of **global** Metadata/RunView/DB Providers in a multi-user environment. Check your code to make sure you are using the providers passed to you in AppContext by MJServer and not calling new Metadata() new RunView() new RunQuery() and similar patterns as those are unstable at times in multi-user server environments!!!'); // global-provider-ok: diagnostic warning text mentions the anti-pattern by name
     }
 
     // Create per-request provider instance based on database type
@@ -406,7 +406,7 @@ async function createPostgresProvider(): Promise<DatabaseProviderBase> {
   );
 
   // Share the connection pool from the primary provider to avoid pool exhaustion
-  const primaryProvider = Metadata.Provider as unknown as { DatabaseConnection?: import('pg').Pool };
+  const primaryProvider = Metadata.Provider as unknown as { DatabaseConnection?: import('pg').Pool }; // global-provider-ok: bootstrap (per-connection PG pool sharing)
   if (primaryProvider?.DatabaseConnection) {
     await pgProvider.ConfigWithSharedPool(pgConfig, primaryProvider.DatabaseConnection);
   } else {