@memberjunction/server 5.43.0 → 5.44.0

package/src/index.ts

@@ -40,6 +40,7 @@ import createMSSQLConfig from './orm.js';
 import { setupRESTEndpoints } from './rest/setupRESTEndpoints.js';
 import { createOAuthCallbackHandler } from './rest/OAuthCallbackHandler.js';
 import { createSignatureWebhookHandler } from './rest/SignatureWebhookHandler.js';
+import { createMediaStreamRouter } from './rest/MediaStreamHandler.js';
 import { createMagicLinkHandler, registerMagicLinkAuthProvider, MAGIC_LINK_MOUNT_PATH } from './auth/magicLink/index.js';
 
 import { resolve } from 'node:path';
@@ -162,6 +163,8 @@ export * from './resolvers/ISAEntityResolver.js';
 export * from './resolvers/ArtifactFileResolver.js';
 export * from './resolvers/FileCategoryResolver.js';
 export * from './resolvers/FileResolver.js';
+export * from './rest/MediaAccessKeys.js';
+export * from './rest/MediaStreamHandler.js';
 export * from './resolvers/InfoResolver.js';
 export * from './resolvers/PotentialDuplicateRecordResolver.js';
 export * from './resolvers/RunTestResolver.js';
@@ -991,6 +994,13 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
   app.use('/esignature', cors<cors.CorsRequest>(), createSignatureWebhookHandler());
   startupLog.LogIf('verbose', '[eSignature] Webhook route registered at /esignature/webhook/:driverKey');
 
+  // ─── Authenticated media streaming (token-gated, registered BEFORE auth) ─────
+  // The `?token=` query param (minted by CreateMediaAccessToken after a per-user permission
+  // check) is the capability — the route verifies it itself, so it does NOT use the MJ bearer
+  // auth middleware (an <audio>/<video> element can't send Authorization headers).
+  app.use('/media', cors<cors.CorsRequest>(), createMediaStreamRouter());
+  startupLog.LogIf('verbose', '[Media] Streaming route registered at /media/:fileId');
+
   // ─── Magic-link routes (MJ-issued, app-scoped external access) ───────────
   // Public router (JWKS + redeem) mounts BEFORE the auth middleware; the
   // authenticated invite-creation router mounts AFTER it (see below).

package/src/resolvers/FileResolver.ts

@@ -1,6 +1,7 @@
-import { EntityPermissionType, FieldValueCollection, EntitySaveOptions } from '@memberjunction/core';
+import { EntityPermissionType, FieldValueCollection, EntitySaveOptions, LogError, UserInfo } from '@memberjunction/core';
 import { NormalizeUUID } from '@memberjunction/global';
 import { MJFileEntity, MJFileStorageProviderEntity, MJFileStorageAccountEntity } from '@memberjunction/core-entities';
+import { readRealtimeRecordingFile } from '@memberjunction/ai-agents';
 import {
   AppContext,
   Arg,
@@ -8,6 +9,7 @@ import {
   DeleteOptionsInput,
   Field,
   FieldResolver,
+  Float,
   InputType,
   Int,
   Mutation,
@@ -37,6 +39,9 @@ import {
 import { CreateMJFileInput, MJFileResolver as FileResolverBase, MJFile_, UpdateMJFileInput } from '../generated/generated.js';
 import { FieldMapper } from '@memberjunction/graphql-dataprovider';
 import { GetReadOnlyProvider } from '../util.js';
+import { configInfo } from '../config.js';
+import { MediaAccessKeyManager } from '../rest/MediaAccessKeys.js';
+import { deriveSidecarPath, parsePeaksSidecar } from './peaksSidecar.js';
 
 @InputType()
 export class CreateUploadURLInput {
@@ -312,8 +317,161 @@ export class SearchAcrossAccountsPayload {
   failedAccounts: number;
 }
 
+/**
+ * Result of {@link FileResolver.GetFileContents} — the bytes of an `MJ: Files` record returned as
+ * base64, read server-side through authenticated MJStorage (never a public pre-signed link).
+ */
+@ObjectType()
+export class FileContentsResult {
+  @Field(() => Boolean)
+  Success: boolean;
+
+  @Field(() => String, { nullable: true })
+  Base64?: string;
+
+  @Field(() => String, { nullable: true })
+  MimeType?: string;
+
+  @Field(() => String, { nullable: true })
+  ErrorMessage?: string;
+}
+
+/**
+ * Result of {@link FileResolver.CreateMediaAccessToken} — a short-lived signed token plus the
+ * authenticated streaming URL the browser hands to a `<audio>`/`<video>` element. The token is
+ * minted only after a per-user permission check on the `MJ: Files` row; the `/media/:fileId`
+ * route re-verifies it (signature + expiry + file match) on each Range request.
+ */
+@ObjectType()
+export class MediaAccessTokenResult {
+  @Field(() => Boolean)
+  Success: boolean;
+
+  @Field(() => String, { nullable: true })
+  Token?: string;
+
+  @Field(() => String, { nullable: true })
+  Url?: string;
+
+  @Field(() => Date, { nullable: true })
+  ExpiresAt?: Date;
+
+  /**
+   * The file's MIME type (from the already-loaded `MJ: Files` row). Lets the wrapper choose
+   * `<audio>` vs `<video>` WITHOUT re-downloading any bytes; the stream itself sets Content-Type.
+   */
+  @Field(() => String, { nullable: true })
+  MimeType?: string;
+
+  /**
+   * Optional precomputed waveform peaks (normalized `0..1`, one per rendered bar) read from a
+   * `peaks.json` sidecar that sits beside the file in storage. When present, the player renders the
+   * real waveform instantly with NO client-side fetch/decode of the audio. Best-effort: a missing or
+   * malformed sidecar simply omits this field — it never blocks token minting or fails the mutation.
+   */
+  @Field(() => [Float], { nullable: true })
+  Peaks?: number[];
+
+  @Field(() => String, { nullable: true })
+  ErrorMessage?: string;
+}
+
 @Resolver(MJFile_)
 export class FileResolver extends FileResolverBase {
+  /**
+   * Resolves the server's public base URL the same way callbacks/magic-link do:
+   * `publicUrl` if configured (e.g. an ngrok URL), else `baseUrl:graphqlPort`. Trailing
+   * slash stripped so callers can append `/media/...`.
+   */
+  private resolvePublicBaseUrl(): string {
+    const base = configInfo.publicUrl || `${configInfo.baseUrl}:${configInfo.graphqlPort}${configInfo.graphqlRootPath || ''}`;
+    return base.replace(/\/+$/, '');
+  }
+
+  /**
+   * Mints a short-lived signed media-access token for an `MJ: Files` record and returns the
+   * authenticated streaming URL (`<publicBase>/media/<fileId>?token=<token>`). Permission-gated
+   * IDENTICALLY to {@link GetFileContents}: the file is loaded under the CALLING USER's context, so
+   * MJ row-level security determines access. The returned token is the capability — the streaming
+   * route re-verifies it without re-checking row-level access. Never throws to the client.
+   *
+   * @param fileId The `MJ: Files` id to grant streaming access to.
+   * @returns `{ Success, Token?, Url?, ExpiresAt?, ErrorMessage? }`.
+   */
+  @Mutation(() => MediaAccessTokenResult)
+  async CreateMediaAccessToken(@Arg('fileId', () => String) fileId: string, @Ctx() context: AppContext): Promise<MediaAccessTokenResult> {
+    try {
+      const provider = GetReadOnlyProvider(context.providers, { allowFallbackToReadWrite: true });
+      const contextUser = this.GetUserFromPayload(context.userPayload);
+
+      // Permission gate: load the file under the USER's context. A failed load means the file
+      // does not exist OR the user lacks read access under MJ row-level security.
+      const fileEntity = await provider.GetEntityObject<MJFileEntity>('MJ: Files', contextUser);
+      const loaded = await fileEntity.Load(fileId);
+      if (!loaded) {
+        return { Success: false, ErrorMessage: 'You do not have access to this file or it does not exist.' };
+      }
+
+      // Access authorized — mint the capability token.
+      const { Token, ExpiresAt } = MediaAccessKeyManager.Instance.Sign(fileId, contextUser.ID);
+      const url = `${this.resolvePublicBaseUrl()}/media/${encodeURIComponent(fileId)}?token=${encodeURIComponent(Token)}`;
+
+      // Best-effort: surface precomputed waveform peaks from a peaks.json sidecar beside the file, so
+      // the player renders the real waveform instantly without fetching/decoding the audio. Never
+      // blocks token minting — any failure just omits Peaks.
+      const peaks = await this.tryReadPeaksSidecar(fileEntity, contextUser);
+
+      return { Success: true, Token, Url: url, ExpiresAt, MimeType: fileEntity.ContentType ?? undefined, Peaks: peaks };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      LogError(`CreateMediaAccessToken failed (file ${fileId}): ${message}`);
+      return { Success: false, ErrorMessage: message };
+    }
+  }
+
+  /**
+   * Best-effort read of a `peaks.json` waveform sidecar that sits in the SAME storage folder as the
+   * given file (a JSON array of normalized `0..1` numbers, written at capture time). Derives the
+   * folder from the file's `ProviderKey` (strips the final path segment), reads `<folder>/peaks.json`
+   * via the file's own storage driver, parses + validates it, and returns sanitized peaks. Returns
+   * `undefined` on ANY failure (no ProviderKey, no sidecar, parse error, garbage) — the caller treats
+   * peaks as a pure optimization and must never let a sidecar problem affect token minting.
+   *
+   * @param file The already-loaded (under the user's context) `MJ: Files` row.
+   * @param contextUser The calling user — used to resolve the storage driver.
+   * @returns Sanitized `0..1` peaks (length-capped), or `undefined`.
+   */
+  private async tryReadPeaksSidecar(file: MJFileEntity, contextUser: UserInfo): Promise<number[] | undefined> {
+    try {
+      // The sidecar lives next to the recording: replace the final path segment with peaks.json.
+      const sidecarPath = deriveSidecarPath(file.ProviderKey);
+      if (!sidecarPath) {
+        return undefined;
+      }
+
+      // Resolve the file's storage account → driver (mirror of readRealtimeRecordingFile's pattern).
+      await FileStorageEngine.Instance.Config(false, contextUser);
+      let accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+      if (accounts.length === 0) {
+        await FileStorageEngine.Instance.Config(true, contextUser);
+        accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+      }
+      const account = accounts[0];
+      if (!account) {
+        return undefined;
+      }
+      const driver = await FileStorageEngine.Instance.GetDriver(account.ID, contextUser);
+      const bytes = await driver.GetObject({ fullPath: sidecarPath });
+      if (!bytes || bytes.length === 0) {
+        return undefined;
+      }
+      return parsePeaksSidecar(bytes);
+    } catch {
+      // No sidecar / unreadable / parse failure — peaks are optional, never surface the error.
+      return undefined;
+    }
+  }
+
   /**
    * Builds UserContextOptions for storage operations that may require OAuth authentication.
    * This passes the current user's ID and context to allow the storage utilities to
@@ -431,6 +589,46 @@ export class FileResolver extends FileResolverBase {
     return url;
   }
 
+  /**
+   * Returns an `MJ: Files` record's bytes as base64, read server-side through authenticated MJStorage
+   * (`GetObject`) — NOT a public pre-signed link. Permission-gated: the file is first loaded under the
+   * calling user's context, so MJ row-level security determines access. Never throws to the client.
+   *
+   * @param fileId The `MJ: Files` id whose bytes to return.
+   * @returns `{ Success, Base64?, MimeType?, ErrorMessage? }`.
+   */
+  @Query(() => FileContentsResult)
+  async GetFileContents(@Arg('fileId', () => String) fileId: string, @Ctx() context: AppContext): Promise<FileContentsResult> {
+    try {
+      const provider = GetReadOnlyProvider(context.providers, { allowFallbackToReadWrite: true });
+      const contextUser = this.GetUserFromPayload(context.userPayload);
+
+      // Permission gate FIRST: load the file record under the USER's context. A failed load means the
+      // file does not exist OR the user lacks read access under MJ row-level security.
+      const fileEntity = await provider.GetEntityObject<MJFileEntity>('MJ: Files', contextUser);
+      const loaded = await fileEntity.Load(fileId);
+      if (!loaded) {
+        return { Success: false, ErrorMessage: 'You do not have access to this file or it does not exist.' };
+      }
+
+      // Read the bytes via authenticated MJStorage (server-side GetObject on the file's own account).
+      const result = await readRealtimeRecordingFile(fileId, contextUser, provider);
+      if (!result) {
+        return { Success: false, ErrorMessage: 'The file could not be read from storage.' };
+      }
+
+      return {
+        Success: true,
+        Base64: result.Bytes.toString('base64'),
+        MimeType: result.MimeType ?? fileEntity.ContentType ?? undefined,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      LogError(`GetFileContents failed (file ${fileId}): ${message}`);
+      return { Success: false, ErrorMessage: message };
+    }
+  }
+
   @Mutation(() => MJFile_)
   async UpdateFile(@Arg('input', () => UpdateMJFileInput) input: UpdateMJFileInput, @Ctx() context: AppContext, @PubSub() pubSub: PubSubEngine) {
     // if the name is changing, rename the target object as well

package/src/resolvers/QueryResolver.ts

@@ -1,5 +1,5 @@
 import { Arg, Ctx, ObjectType, Query, Resolver, Field, Int, InputType } from 'type-graphql';
-import { RunQuery, IRunQueryProvider, IMetadataProvider, RunQueryParams, LogError, RunQueryWithCacheCheckParams, RunQueriesWithCacheCheckResponse, RunQueryWithCacheCheckResult } from '@memberjunction/core';
+import { RunQuery, IRunQueryProvider, IMetadataProvider, RunQueryParams, LogError, RunQueryWithCacheCheckParams, RunQueriesWithCacheCheckResponse, RunQueryWithCacheCheckResult, RunQueryEnrichment } from '@memberjunction/core';
 import { AppContext } from '../types.js';
 import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { GraphQLJSONObject } from 'graphql-type-json';
@@ -40,6 +40,9 @@ export class RunQueryInput {
 
   @Field(() => String, { nullable: true, description: 'Description to use in audit log' })
   AuditLogDescription?: string;
+
+  @Field(() => GraphQLJSONObject, { nullable: true, description: 'Optional runtime-only directive to post-process result rows through a registered query result enricher ({ EnricherKey, Config })' })
+  Enrichment?: RunQueryEnrichment;
 }
 
 @ObjectType()
@@ -191,7 +194,8 @@ export class RunQueryResolver extends ResolverBase {
                      @Arg('MaxRows', () => Int, {nullable: true}) MaxRows?: number,
                      @Arg('StartRow', () => Int, {nullable: true}) StartRow?: number,
                      @Arg('ForceAuditLog', () => Boolean, {nullable: true}) ForceAuditLog?: boolean,
-                     @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string): Promise<RunQueryResultType> {
+                     @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string,
+                     @Arg('Enrichment', () => GraphQLJSONObject, {nullable: true}) Enrichment?: RunQueryEnrichment): Promise<RunQueryResultType> {
     // Check API key scope authorization for query execution
     await this.CheckAPIKeyScopeAuthorization('query:run', QueryID, context.userPayload);
 
@@ -200,7 +204,7 @@ export class RunQueryResolver extends ResolverBase {
     const rq = new RunQuery(provider as unknown as IRunQueryProvider);
     console.log('GetQueryData called with:', { QueryID, Parameters, MaxRows, StartRow, ForceAuditLog, AuditLogDescription });
     const result = await rq.RunQuery(
-      { 
+      {
         QueryID: QueryID,
         CategoryID: CategoryID,
         CategoryPath: CategoryPath,
@@ -208,8 +212,9 @@ export class RunQueryResolver extends ResolverBase {
         MaxRows: MaxRows,
         StartRow: StartRow,
         ForceAuditLog: ForceAuditLog,
-        AuditLogDescription: AuditLogDescription
-      }, 
+        AuditLogDescription: AuditLogDescription,
+        Enrichment: Enrichment
+      },
       context.userPayload.userRecord);
     console.log('RunQuery result:', { 
       Success: result.Success, 
@@ -256,22 +261,24 @@ export class RunQueryResolver extends ResolverBase {
                            @Arg('MaxRows', () => Int, {nullable: true}) MaxRows?: number,
                            @Arg('StartRow', () => Int, {nullable: true}) StartRow?: number,
                            @Arg('ForceAuditLog', () => Boolean, {nullable: true}) ForceAuditLog?: boolean,
-                           @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string): Promise<RunQueryResultType> {
+                           @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string,
+                           @Arg('Enrichment', () => GraphQLJSONObject, {nullable: true}) Enrichment?: RunQueryEnrichment): Promise<RunQueryResultType> {
     // Check API key scope authorization for query execution
     await this.CheckAPIKeyScopeAuthorization('query:run', QueryName, context.userPayload);
 
     const provider = GetReadOnlyProvider(context.providers, {allowFallbackToReadWrite: true});
     const rq = new RunQuery(provider as unknown as IRunQueryProvider);
     const result = await rq.RunQuery(
-      { 
-        QueryName: QueryName, 
+      {
+        QueryName: QueryName,
         CategoryID: CategoryID,
         CategoryPath: CategoryPath,
         Parameters: Parameters,
         MaxRows: MaxRows,
         StartRow: StartRow,
         ForceAuditLog: ForceAuditLog,
-        AuditLogDescription: AuditLogDescription
+        AuditLogDescription: AuditLogDescription,
+        Enrichment: Enrichment
       },
       context.userPayload.userRecord);
       
@@ -302,13 +309,14 @@ export class RunQueryResolver extends ResolverBase {
                                @Arg('MaxRows', () => Int, {nullable: true}) MaxRows?: number,
                                @Arg('StartRow', () => Int, {nullable: true}) StartRow?: number,
                                @Arg('ForceAuditLog', () => Boolean, {nullable: true}) ForceAuditLog?: boolean,
-                               @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string): Promise<RunQueryResultType> {
+                               @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string,
+                               @Arg('Enrichment', () => GraphQLJSONObject, {nullable: true}) Enrichment?: RunQueryEnrichment): Promise<RunQueryResultType> {
     const provider = GetReadOnlyProvider(context.providers, {allowFallbackToReadWrite: true});
     const md = provider as unknown as IMetadataProvider;
     const rq = new RunQuery(provider as unknown as IRunQueryProvider);
 
     const result = await rq.RunQuery(
-      { 
+      {
         QueryID: QueryID,
         CategoryID: CategoryID,
         CategoryPath: CategoryPath,
@@ -316,8 +324,9 @@ export class RunQueryResolver extends ResolverBase {
         MaxRows: MaxRows,
         StartRow: StartRow,
         ForceAuditLog: ForceAuditLog,
-        AuditLogDescription: AuditLogDescription
-      }, 
+        AuditLogDescription: AuditLogDescription,
+        Enrichment: Enrichment
+      },
       context.userPayload.userRecord);
     
     // If QueryName is not populated by the provider, use efficient lookup
@@ -360,12 +369,13 @@ export class RunQueryResolver extends ResolverBase {
                                      @Arg('MaxRows', () => Int, {nullable: true}) MaxRows?: number,
                                      @Arg('StartRow', () => Int, {nullable: true}) StartRow?: number,
                                      @Arg('ForceAuditLog', () => Boolean, {nullable: true}) ForceAuditLog?: boolean,
-                                     @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string): Promise<RunQueryResultType> {
+                                     @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string,
+                                     @Arg('Enrichment', () => GraphQLJSONObject, {nullable: true}) Enrichment?: RunQueryEnrichment): Promise<RunQueryResultType> {
     const provider = GetReadOnlyProvider(context.providers, {allowFallbackToReadWrite: true});
     const rq = new RunQuery(provider as unknown as IRunQueryProvider);
 
     const result = await rq.RunQuery(
-      { 
+      {
         QueryName: QueryName,
         CategoryID: CategoryID,
         CategoryPath: CategoryPath,
@@ -373,8 +383,9 @@ export class RunQueryResolver extends ResolverBase {
         MaxRows: MaxRows,
         StartRow: StartRow,
         ForceAuditLog: ForceAuditLog,
-        AuditLogDescription: AuditLogDescription
-      }, 
+        AuditLogDescription: AuditLogDescription,
+        Enrichment: Enrichment
+      },
       context.userPayload.userRecord);
     
     return {
@@ -420,7 +431,8 @@ export class RunQueryResolver extends ResolverBase {
       MaxRows: i.MaxRows,
       StartRow: i.StartRow,
       ForceAuditLog: i.ForceAuditLog,
-      AuditLogDescription: i.AuditLogDescription
+      AuditLogDescription: i.AuditLogDescription,
+      Enrichment: i.Enrichment
     }));
 
     // Execute all queries in parallel using the batch method
@@ -469,7 +481,8 @@ export class RunQueryResolver extends ResolverBase {
       MaxRows: i.MaxRows,
       StartRow: i.StartRow,
       ForceAuditLog: i.ForceAuditLog,
-      AuditLogDescription: i.AuditLogDescription
+      AuditLogDescription: i.AuditLogDescription,
+      Enrichment: i.Enrichment
     }));
 
     // Execute all queries in parallel using the batch method
@@ -532,6 +545,7 @@ export class RunQueryResolver extends ResolverBase {
           StartRow: item.params.StartRow,
           ForceAuditLog: item.params.ForceAuditLog,
           AuditLogDescription: item.params.AuditLogDescription,
+          Enrichment: item.params.Enrichment,
         },
         cacheStatus: item.cacheStatus ? {
           maxUpdatedAt: item.cacheStatus.maxUpdatedAt,

package/src/resolvers/RealtimeBridgeResolver.ts

@@ -9,6 +9,7 @@ import { CreateBridgeRealtimeSession, FinalizeBridgeCoAgentRuns, GetRealtimeMode
 import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
 import { SessionManager } from '../agentSessions/SessionManager.js';
 import { NotificationEngine } from '@memberjunction/notifications';
+import { registerMeetingRecordingFile, correlateRecordingStart } from './meetingRecordingRegistration.js';
 
 /**
  * Binds the agent realtime-session factory onto the LiveKit room coordinator's model-session creation seam.
@@ -174,6 +175,10 @@ export class LiveKitRecordingResult {
 
   @Field(() => String)
   Status: string;
+
+  /** The `MJ: Files` row id of the registered recording (set on stop, once the egress MP4 is registered). */
+  @Field(() => String, { nullable: true })
+  RecordingFileID?: string;
 }
 
 /** A selectable provider-native voice for the dev voice picker. */
@@ -444,10 +449,17 @@ export class RealtimeBridgeResolver extends ResolverBase {
     @Ctx() context: AppContext = {} as AppContext,
   ): Promise<LiveKitRecordingResult> {
     try {
-      if (!this.GetUserFromPayload(context.userPayload)) {
+      const user = this.GetUserFromPayload(context.userPayload);
+      if (!user) {
         return { Success: false, ErrorMessage: 'Unable to determine current user.', EgressID: '', Status: '' };
       }
       const info = await new LiveKitEgressService().StartRoomRecording({ RoomName: input.RoomName, Layout: input.Layout });
+
+      // Best-effort: correlate the live recording with the room's Meeting-Room Conversation (if it exists
+      // yet) by stamping its EgressID. Never fail the start on this — the stop-flow resolves/creates it.
+      const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+      void correlateRecordingStart(input.RoomName, info.EgressID, user, provider);
+
       return { Success: true, EgressID: info.EgressID, Status: info.Status };
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
@@ -456,15 +468,35 @@ export class RealtimeBridgeResolver extends ResolverBase {
     }
   }
 
-  /** Stops a recording by egress id. */
+  /**
+   * Stops a recording by egress id, then REGISTERS the completed egress MP4 into MJStorage as an
+   * `MJ: Files` row linked to the room's Meeting-Room Conversation (`Conversation.RecordingFileID`).
+   * Registration is best-effort: a missing storage config or any failure returns the stop result with no
+   * `RecordingFileID` (the recording still stopped) — it never throws.
+   */
   @Mutation(() => LiveKitRecordingResult)
   async StopLiveKitRecording(@Arg('egressID', () => String) egressID: string, @Ctx() context: AppContext = {} as AppContext): Promise<LiveKitRecordingResult> {
     try {
-      if (!this.GetUserFromPayload(context.userPayload)) {
+      const user = this.GetUserFromPayload(context.userPayload);
+      if (!user) {
         return { Success: false, ErrorMessage: 'Unable to determine current user.', EgressID: egressID, Status: '' };
       }
       const info = await new LiveKitEgressService().StopRecording(egressID);
-      return { Success: true, EgressID: info.EgressID, Status: info.Status };
+      const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+
+      // Register the completed egress MP4 as a Files row on the Meeting-Room Conversation. Best-effort:
+      // any failure (e.g. storage provider not configured) leaves RecordingFileID unset but still
+      // returns the successful stop result.
+      const registration = await registerMeetingRecordingFile(
+        { EgressID: info.EgressID, RoomName: info.RoomName, OutputLocation: info.OutputLocation, OutputSizeBytes: info.OutputSizeBytes },
+        user,
+        provider,
+      );
+      if (!registration.Success) {
+        LogError(`StopLiveKitRecording: recording stopped but registration did not complete: ${registration.ErrorMessage ?? 'unknown'}`);
+      }
+
+      return { Success: true, EgressID: info.EgressID, Status: info.Status, RecordingFileID: registration.RecordingFileID };
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
       LogError(`StopLiveKitRecording failed: ${msg}`);